Pensyve智能体内存运行时

Install dependencies (creates .venv automatically)

uv sync --extra dev

Build the native Python module (required before running any Python code)

uv run maturin develop --release -m pensyve-python/Cargo.toml

Install

pip install pensyve          # Python (PyPI)
npm install pensyve          # TypeScript (npm)
go get github.com/major7apps/pensyve/pensyve-go@latest  # Go

Or use the MCP server directly with Claude Code, Cursor, or any MCP client — see MCP Setup.

Recall grouped: feed an LLM reader without rebuilding session blocks

When the consumer of recalled memories is another LLM (the dominant "memory for an AI agent" pattern), recall_grouped() returns memories already clustered by source session and ordered chronologically — ready to format as session blocks in a reader prompt.

```python import pensyve

p = pensyve.Pensyve() groups = p.recall_grouped("How many projects have I led this year?", limit=50)

Building from source

<details> <summary>Prerequisites and build steps</summary>

• Rust 1.88+, Python 3.10+ with uv
• Optional: Bun (TypeScript SDK), Go 1.21+ (Go SDK)

git clone https://github.com/major7apps/pensyve.git && cd pensyve
uv sync --extra dev
uv run maturin develop --release -m pensyve-python/Cargo.toml
uv run python -c "import pensyve; print(pensyve.__version__)"

</details>

First-Time Setup

```bash

Build & Test

make build      # Compile Rust + build PyO3 module
make test       # Run all tests (Rust + Python)
make lint       # clippy + ruff + pyright
make format     # cargo fmt + ruff format
make check      # lint + test (CI gate)

To run test suites individually:

cargo test --workspace                                       # Rust tests
uv run maturin develop --release -m pensyve-python/Cargo.toml  # Build PyO3 module first
uv run pytest tests/python/ -v                               # Python tests
cd pensyve-ts && bun test                                    # TypeScript tests
cd pensyve-go && go test ./...                               # Go tests

Quick Start

pip install pensyve

Environment Variables

Pensyve uses the following environment variables across its components:

Optional Features

Session 1 — agent stores the preference

p.remember(entity=user, fact="Prefers dark mode and vim keybindings", confidence=0.95)

Interfaces

Pensyve exposes its core engine through multiple interfaces — use whichever fits your stack.

Python SDK

Direct in-process access via PyO3. Zero network overhead.

```python import pensyve

p = pensyve.Pensyve(namespace="my-agent") entity = p.entity("user", kind="user")

REST API

Rust/Axum gateway serving REST + MCP with auth, rate limiting, and usage metering.

cargo build --release --bin pensyve-mcp-gateway
./target/release/pensyve-mcp-gateway  # listens on 0.0.0.0:3000

```bash

TypeScript SDK

HTTP client with timeout, retry, and structured errors.

import { Pensyve } from "pensyve";

const p = new Pensyve({
  baseUrl: "http://localhost:3000",
  timeoutMs: 10000,
  retries: 2,
});
await p.remember({ entity: "seth", fact: "Likes TypeScript", confidence: 0.9 });
const memories = await p.recall("programming", { entity: "seth" });

// Session-grouped recall — feed an LLM reader without rebuilding session blocks.
const { groups } = await p.recallGrouped("how many projects did I lead?", {
  limit: 50,
  order: "chronological",
});
for (const g of groups) {
  console.log(`### Session ${g.sessionId} (${g.sessionTime})`);
  for (const m of g.memories) console.log(`  ${m.content}`);
}

Go SDK

Context-aware HTTP client with structured errors.

import pensyve "github.com/major7apps/pensyve/pensyve-go"

client := pensyve.NewClient(pensyve.Config{BaseURL: "http://localhost:3000"})
ctx := context.Background()
client.Remember(ctx, "seth", "Likes Go", 0.9)
memories, _ := client.Recall(ctx, "programming", nil)

Gateway / REST API

Additional SDKs

cd pensyve-ts && bun test          # TypeScript (38 tests)
cd pensyve-go && go test ./...     # Go (17 tests)
cd pensyve-wasm && cargo check     # WASM (standalone)

for "memory as input to an LLM reader" workflows.

groups = p.recall_grouped("programming language", limit=50)

Claude Code Plugin

Full cognitive memory layer for Claude Code with 7 commands, 4 skills, 2 agents, and 6 lifecycle hooks.

Install from the marketplace:

/plugin marketplace add major7apps/pensyve
/plugin install pensyve@major7apps-pensyve
/reload-plugins

The plugin does not bundle an MCP server config — auth method and backend are user choices. Add an mcpServers.pensyve entry to your ~/.claude/settings.json (user-level) or .claude/settings.json (project-level). Pick one:

Pensyve Cloud — API key (recommended):

export PENSYVE_API_KEY="psy_your_key_here"

{
  "mcpServers": {
    "pensyve": {
      "type": "http",
      "url": "https://mcp.pensyve.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PENSYVE_API_KEY}"
      }
    }
  }
}

Pensyve Cloud — OAuth (browser sign-in):

{
  "mcpServers": {
    "pensyve": {
      "type": "http",
      "url": "https://mcp.pensyve.com/mcp"
    }
  }
}

Pensyve Local (self-hosted, no API key):

Build the MCP binary first (see Install), then:

{
  "mcpServers": {
    "pensyve": {
      "command": "pensyve-mcp",
      "args": ["--stdio"]
    }
  }
}

Note: Use headers with Authorization: Bearer for remote MCP (HTTP transport). Use the top-level env block (Claude Code MCP schema) for local stdio servers that read environment variables at startup.

Plugin contents:
├── 7 slash commands   /remember, /recall, /forget, /inspect, /consolidate, /memory-status, /using-pensyve
├── 4 skills           session-memory, memory-informed-refactor, context-loader, memory-review
├── 2 agents           memory-curator (background), context-researcher (on-demand)
└── 6 hooks            SessionStart, Stop, PreCompact, UserPromptSubmit, PostToolUse (Write/Edit, Bash)

See integrations/claude-code/README.md for full documentation.

Recall, clustered by source session (canonical for LLM-reader workflows)

curl -X POST http://localhost:3000/v1/recall_grouped \ -H "Content-Type: application/json" \ -d '{"query": "How many books did I buy?", "limit": 50, "order": "chronological"}' ```

Endpoints: GET /v1/health, POST /v1/recall, POST /v1/recall_grouped, POST /v1/remember, POST /v1/entities, DELETE /v1/entities/{name}, POST /v1/inspect, GET /v1/stats, PATCH /v1/memories/{id}, DELETE /v1/memories/{id}

Retrieval Pipeline

1. Embed query via ONNX (Alibaba-NLP/gte-base-en-v1.5, 768 dims)
2. Classify intent — Question/Action/Recall/General (keyword heuristics)
3. Vector search — cosine similarity against stored embeddings
4. BM25 search — FTS5 lexical matching
5. Graph traversal — petgraph BFS from query entity
6. Fusion scoring — weighted sum of 8 signals (vector, BM25, graph, intent, recency, access, confidence, type boost)
7. Cross-encoder reranking — BGE reranker on top-20 candidates
8. FSRS reinforcement — retrieved memories get stability boost

Verify the module loads

uv run python -c "import pensyve; print(pensyve.version)" ```

Note: The pensyve Python package is a native Rust extension built with PyO3. You must run uv run maturin develop before pytest or any Python import of pensyve, otherwise you will get ModuleNotFoundError: No module named 'pensyve'.