{
"markdown": "\n\n# Pensyve\n\n[](https://github.com/major7apps/pensyve/actions/workflows/ci.yml)\n[](LICENSE)\n[](https://www.python.org/downloads/)\n[](https://www.rust-lang.org/)\n\nUniversal memory runtime for AI agents. Framework-agnostic, protocol-native, offline-first.\n\n### Without memory\n\n```\nUser: \"I prefer dark mode and use vim keybindings\"\nAgent: \"Got it!\"\n\n[next session]\n\nUser: \"Update my editor settings\"\nAgent: \"What settings would you like to change?\"\nUser: \"I ALREADY TOLD YOU\"\n```\n\n### With Pensyve\n\n```python\n# Session 1 — agent stores the preference\np.remember(entity=user, fact=\"Prefers dark mode and vim keybindings\", confidence=0.95)\n\n# Session 2 — agent recalls it automatically\nmemories = p.recall(\"editor settings\", entity=user)\n# → [Memory: \"Prefers dark mode and vim keybindings\" (score: 0.94)]\n```\n\nYour agent stops being amnesiac. Decisions, patterns, and outcomes persist across sessions — and the right context surfaces when it's needed.\n\n## Why Pensyve\n\n| What you need | How Pensyve solves it |\n| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| Agent forgets everything between sessions | **Three memory types** — episodic (what happened), semantic (what is known), procedural (what works) |\n| Agent can't find the right memory | **8-signal fusion retrieval** — vector similarity + BM25 + graph + intent + recency + frequency + confidence + type boost |\n| Agent repeats failed approaches | **Procedural memory** — Bayesian tracking on action→outcome pairs surfaces what actually works |\n| Memory store grows unbounded | **FSRS forgetting curve** — memories you use get stronger, unused ones fade naturally. Consolidation promotes repeated facts. |\n| Need cloud signup to get started | **Offline-first** — SQLite + ONNX embeddings. Works on your laptop right now. No API keys needed. |\n| Need to scale to production | **Postgres backend** — feature-gated pgvector for multi-node deployments. Managed service at pensyve.com. |\n| Only works with one framework | **Framework-agnostic** — Python, TypeScript, Go, MCP, REST, CLI. Drop-in adapters for LangChain, CrewAI, AutoGen. |\n\n## Install\n\n```bash\npip install pensyve # Python (PyPI)\nnpm install @pensyve/sdk # TypeScript (npm)\ngo get github.com/major7apps/pensyve/pensyve-go/v3@latest # Go\n```\n\nOr use the MCP server directly with Antigravity CLI, Codex, Claude Code, Cursor, or any MCP client — see [MCP Setup](https://pensyve.com/docs/getting-started/mcp-setup).\n\n## Quick Start\n\n```bash\npip install pensyve\n```\n\n### Episode: your agent remembers a conversation\n\n```python\nimport pensyve\n\np = pensyve.Pensyve()\nuser = p.entity(\"user\", kind=\"user\")\n\n# Record a conversation — Pensyve captures it as episodic memory\nwith p.episode(user) as ep:\n ep.message(\"user\", \"I prefer dark mode and use vim keybindings\")\n ep.message(\"agent\", \"Got it — I'll remember your editor preferences\")\n ep.outcome(\"success\")\n\n# Later (even in a new session), the agent recalls what happened\nresults = p.recall(\"editor preferences\", entity=user)\nfor r in results:\n print(f\"[{r.score:.2f}] {r.content}\")\n```\n\n### Recall grouped: feed an LLM reader without rebuilding session blocks\n\nWhen the consumer of recalled memories is another LLM (the dominant\n\"memory for an AI agent\" pattern), `recall_grouped()` returns memories\nalready clustered by source session and ordered chronologically — ready\nto format as session blocks in a reader prompt.\n\n```python\nimport pensyve\n\np = pensyve.Pensyve()\ngroups = p.recall_grouped(\"How many projects have I led this year?\", limit=50)\n\n# Each group is one conversation session — feed it to a reader directly.\nfor i, g in enumerate(groups, start=1):\n print(f\"### Session {i} ({g.session_time}):\")\n for m in g.memories:\n print(f\" {m.content}\")\n```\n\nNo more manual `OrderedDict` clustering, no more reordering by date string,\nno more boilerplate every consumer has to reinvent.\n\n### Remember: store an explicit fact\n\n```python\np.remember(entity=user, fact=\"Prefers Python over JavaScript\", confidence=0.9)\n```\n\n### Procedural: the agent learns what works\n\n```python\n# After a debugging session that succeeded:\nep.outcome(\"success\")\n\n# Pensyve tracks action→outcome reliability with Bayesian updates.\n# Next time a similar issue comes up, recall surfaces the approach that worked.\n```\n\n### Consolidate: memories stay clean\n\n```python\np.consolidate()\n# Promotes repeated episodic facts to semantic knowledge\n# Decays memories you never access via FSRS forgetting curve\n```\n\n### Building from source\n\n\nPrerequisites and build steps
\n\n- Rust 1.88+, Python 3.10+ with [uv](https://github.com/astral-sh/uv)\n- Optional: [Bun](https://bun.sh) (TypeScript SDK), [Go 1.21+](https://go.dev) (Go SDK)\n\n```bash\ngit clone https://github.com/major7apps/pensyve.git && cd pensyve\nuv sync --extra dev\nuv run maturin develop --release -m pensyve-python/Cargo.toml\nuv run python -c \"import pensyve; print(pensyve.__version__)\"\n```\n\n \n\n## Interfaces\n\nPensyve exposes its core engine through multiple interfaces — use whichever fits your stack.\n\n### Python SDK\n\nDirect in-process access via PyO3. Zero network overhead.\n\n```python\nimport pensyve\n\np = pensyve.Pensyve(namespace=\"my-agent\")\nentity = p.entity(\"user\", kind=\"user\")\n\n# Remember a fact\np.remember(entity=entity, fact=\"User prefers Python\", confidence=0.95)\n\n# Recall memories (flat list)\nresults = p.recall(\"programming language\", entity=entity)\n\n# Recall memories clustered by source session — the canonical entry point\n# for \"memory as input to an LLM reader\" workflows.\ngroups = p.recall_grouped(\"programming language\", limit=50)\n\n# Record an episode\nwith p.episode(entity) as ep:\n ep.message(\"user\", \"Can you fix the login bug?\")\n ep.message(\"agent\", \"Fixed — the session token was expiring early\")\n ep.outcome(\"success\")\n\n# Consolidate (promote repeated facts, decay unused memories)\np.consolidate()\n```\n\n### MCP Server\n\nWorks with Antigravity CLI, Claude Code, Cursor, and any MCP-compatible client.\n\n```bash\ncargo build --release --bin pensyve-mcp\n```\n\n```json\n{\n \"mcpServers\": {\n \"pensyve\": {\n \"command\": \"./target/release/pensyve-mcp\",\n \"env\": { \"PENSYVE_PATH\": \"~/.pensyve/default\" }\n }\n }\n}\n```\n\n**Tools exposed:** `recall`, `remember`, `episode_start`, `episode_end`, `forget`, `inspect`, `status`, `account`\n\n### Claude Code Plugin\n\nFull cognitive memory layer for Claude Code with 7 commands, 4 skills, 2 agents, and 6 lifecycle hooks.\n\nInstall from the marketplace:\n\n```\n/plugin marketplace add major7apps/pensyve\n/plugin install pensyve@major7apps-pensyve\n/reload-plugins\n```\n\nThe 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:\n\n**Pensyve Cloud — API key (recommended):**\n\n```bash\nexport PENSYVE_API_KEY=\"psy_your_key_here\"\n```\n\n```json\n{\n \"mcpServers\": {\n \"pensyve\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.pensyve.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${PENSYVE_API_KEY}\"\n }\n }\n }\n}\n```\n\n**Pensyve Cloud — OAuth (browser sign-in):**\n\n```json\n{\n \"mcpServers\": {\n \"pensyve\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.pensyve.com/mcp\"\n }\n }\n}\n```\n\n**Pensyve Local (self-hosted, no API key):**\n\nBuild the MCP binary first (see [Install](#install)), then:\n\n```json\n{\n \"mcpServers\": {\n \"pensyve\": {\n \"command\": \"pensyve-mcp\",\n \"args\": [\"--stdio\"]\n }\n }\n}\n```\n\n> **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.\n\n```\nPlugin contents:\n├── 7 slash commands /remember, /recall, /forget, /inspect, /consolidate, /memory-status, /using-pensyve\n├── 4 skills session-memory, memory-informed-refactor, context-loader, memory-review\n├── 2 agents memory-curator (background), context-researcher (on-demand)\n└── 6 hooks SessionStart, Stop, PreCompact, UserPromptSubmit, PostToolUse (Write/Edit, Bash)\n```\n\nSee [`integrations/claude-code/README.md`](integrations/claude-code/README.md) for full documentation.\n\n### Codex Plugin\n\nFirst-class working memory for OpenAI Codex with a plugin manifest, bundled MCP server config, hooks, skills, `/pensyve`, and `$pensyve` skill invocation.\n\nAdd this repo as a Codex plugin marketplace, then install Pensyve:\n\n```bash\ncodex plugin marketplace add major7apps/pensyve\ncodex plugin add pensyve@pensyve-codex\n```\n\nFor local development from a checkout, use\n`codex plugin marketplace add /path/to/pensyve/integrations/codex-plugin` instead.\n\nSet your API key for the bundled MCP server:\n\n```bash\nexport PENSYVE_API_KEY=\"psy_your_key_here\"\n```\n\nThe plugin bundles `integrations/codex-plugin/.mcp.json`, so Codex can load the Pensyve MCP server without copying a project config file. Use `/skills`, `$pensyve`, or `/pensyve` for explicit memory work, or let the bundled hooks and instructions prompt Codex to recall before substantive project decisions. `@pensyve` is documented as a text-level compatibility convention; true native Codex @-mention dispatch still needs platform support.\n\nSee [`integrations/codex-plugin/README.md`](integrations/codex-plugin/README.md) for the manual fallback and local-stdio setup.\n\n### Antigravity CLI Plugin\n\nInstall the native Pensyve plugin for Google Antigravity CLI:\n\n```bash\nagy plugin install https://github.com/major7apps/pensyve/tree/main/integrations/antigravity-plugin\n```\n\nThe plugin bundles eight working-memory rules, eight skills, and a URL-only remote MCP definition. Open `/mcp` in Antigravity and authenticate Pensyve in the browser; no API key is stored in the plugin.\n\nSee [`integrations/antigravity-plugin/README.md`](integrations/antigravity-plugin/README.md) for MCP-only, local-stdio, and migration setup.\n\n### REST API\n\nRust/Axum gateway serving REST + MCP with auth, rate limiting, and usage metering.\n\n```bash\ncargo build --release --bin pensyve-mcp-gateway\n./target/release/pensyve-mcp-gateway # listens on 0.0.0.0:3000\n```\n\n```bash\n# Remember\ncurl -X POST http://localhost:3000/v1/remember \\\n -H \"Content-Type: application/json\" \\\n -d '{\"entity\": \"seth\", \"fact\": \"Seth prefers Python\", \"confidence\": 0.95}'\n\n# Recall\ncurl -X POST http://localhost:3000/v1/recall \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"programming language\", \"entity\": \"seth\"}'\n\n# Recall, clustered by source session (canonical for LLM-reader workflows)\ncurl -X POST http://localhost:3000/v1/recall_grouped \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"How many books did I buy?\", \"limit\": 50, \"order\": \"chronological\"}'\n```\n\n**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}`\n\n### TypeScript SDK\n\nHTTP client with timeout, retry, and structured errors.\n\n```typescript\nimport { Pensyve } from \"@pensyve/sdk\";\n\nconst p = new Pensyve({\n baseUrl: \"http://localhost:3000\",\n timeoutMs: 10000,\n retries: 2,\n});\nawait p.remember({ entity: \"seth\", fact: \"Likes TypeScript\", confidence: 0.9 });\nconst memories = await p.recall(\"programming\", { entity: \"seth\" });\n\n// Session-grouped recall — feed an LLM reader without rebuilding session blocks.\nconst { groups } = await p.recallGrouped(\"how many projects did I lead?\", {\n limit: 50,\n order: \"chronological\",\n});\nfor (const g of groups) {\n console.log(`### Session ${g.sessionId} (${g.sessionTime})`);\n for (const m of g.memories) console.log(` ${m.content}`);\n}\n```\n\n### Go SDK\n\nContext-aware HTTP client with structured errors.\n\n```go\nimport pensyve \"github.com/major7apps/pensyve/pensyve-go/v3\"\n\nclient := pensyve.NewClient(pensyve.Config{BaseURL: \"http://localhost:3000\"})\nctx := context.Background()\nclient.Remember(ctx, \"seth\", \"Likes Go\", 0.9)\nmemories, _ := client.Recall(ctx, \"programming\", nil)\n```\n\n### CLI\n\n```bash\ncargo build --bin pensyve-cli\n\n# Recall memories (default output is JSON; use --format text for human-readable)\n./target/debug/pensyve-cli recall \"editor preferences\" --entity user\n\n# Show namespace status with memory counts\n./target/debug/pensyve-cli status\n\n# Show stats\n./target/debug/pensyve-cli stats\n\n# Inspect an entity\n./target/debug/pensyve-cli inspect --entity user\n```\n\n## Environment Variables\n\nPensyve uses the following environment variables across its components:\n\n### Core\n\n| Variable | Default | Description |\n| ----------------------------- | ------------------------ | --------------------------------------------------------- |\n| `PENSYVE_PATH` | `~/.pensyve/` | SQLite database directory |\n| `PENSYVE_NAMESPACE` | `default` | Memory namespace name |\n| `RUST_LOG` | `pensyve=info` | Tracing filter (e.g. `debug`, `pensyve=debug,hyper=warn`) |\n| `PENSYVE_ALLOW_MOCK_EMBEDDER` | `false` | Fall back to mock embedder if real models unavailable (eager startup only, i.e. with `PENSYVE_EAGER_EMBEDDER=1`) |\n| `PENSYVE_EAGER_EMBEDDER` | `false` | Load the ONNX model at startup instead of on first use |\n\n### Gateway / REST API\n\n| Variable | Default | Description |\n| ------------------------ | --------- | ------------------------------------------------ |\n| `PENSYVE_API_KEYS` | _(empty)_ | Comma-separated valid API keys (standalone mode) |\n| `PENSYVE_VALIDATION_URL` | _(none)_ | Remote endpoint for API key validation |\n| `PENSYVE_RATE_LIMIT` | `300` | Max requests per minute per API key |\n| `HOST` | `0.0.0.0` | Server bind address |\n| `PORT` | `3000` | Server bind port |\n\n### Cloud / Managed Service\n\n| Variable | Default | Description |\n| ---------------------- | ----------------------- | ----------------------------- |\n| `PENSYVE_API_KEY` | _(none)_ | Cloud API key for remote mode |\n| `PENSYVE_REMOTE_URL` | `http://localhost:8000` | Remote server URL |\n| `DATABASE_URL` | _(none)_ | Postgres connection string |\n| `REDIS_URL` | _(none)_ | Redis for caching, rate limiting, daily quotas |\n\n### Quotas (managed service)\n\n| Variable | Default | Description |\n| ------------------------------- | --------- | ------------------------------- |\n| `PENSYVE_MAX_NAMESPACES` | unlimited | Max namespaces per account |\n| `PENSYVE_MAX_MEMORIES` | unlimited | Max total memories per account |\n| `PENSYVE_MAX_RECALLS_PER_MONTH` | unlimited | Max recall operations per month |\n| `PENSYVE_MAX_STORAGE_BYTES` | unlimited | Max storage bytes per account |\n\n### Optional Features\n\n| Variable | Default | Description |\n| -------------------------- | -------- | ---------------------------- |\n| `PENSYVE_TIER2_ENABLED` | `false` | Enable Tier 2 LLM extraction |\n| `PENSYVE_TIER2_MODEL_PATH` | _(none)_ | Path to GGUF model file |\n| `PENSYVE_OTEL_ENDPOINT` | _(none)_ | OpenTelemetry collector URL |\n\n## Architecture\n\n\n\n### Data Model\n\n```\nNamespace (isolation boundary)\n └── Entity (agent | user | team | tool)\n ├── Episodes (bounded interaction sequences)\n │ └── Messages (role + content)\n └── Memories\n ├── Episodic — what happened (timestamped, multimodal content type)\n ├── Semantic — what is known (SPO triples with temporal validity)\n └── Procedural — what works (action→outcome with Bayesian reliability)\n```\n\n### Retrieval Pipeline\n\n1. **Embed** query via ONNX (Alibaba-NLP/gte-base-en-v1.5, 768 dims)\n2. **Classify intent** — Question/Action/Recall/General (keyword heuristics)\n3. **Vector search** — cosine similarity against stored embeddings\n4. **BM25 search** — FTS5 lexical matching\n5. **Graph traversal** — petgraph BFS from query entity\n6. **Fusion scoring** — weighted sum of 8 signals (vector, BM25, graph, intent, recency, access, confidence, type boost)\n7. **Cross-encoder reranking** — BGE reranker on top-20 candidates\n8. **FSRS reinforcement** — retrieved memories get stability boost\n\n## Project Structure\n\n```\npensyve/\n├── pensyve-core/ Rust engine (rlib) — storage, embedding, retrieval, graph, decay, mesh, observability\n├── pensyve-python/ Python SDK via PyO3 (cdylib)\n├── pensyve-mcp/ MCP server binary (stdio, rmcp)\n├── pensyve-cli/ CLI binary (clap)\n├── pensyve-ts/ TypeScript SDK (bun) — timeout, retry, PensyveError\n├── pensyve-go/ Go SDK — context-aware HTTP client\n├── pensyve-wasm/ WASM build — standalone minimal in-memory Pensyve\n├── pensyve_server/ Shared Python utilities — billing, extraction\n├── integrations/ All integrations — IDE plugins, framework adapters, code harnesses\n│ ├── claude-code/ Claude Code plugin (commands, skills, agents, hooks)\n│ ├── antigravity-plugin/ Antigravity plugin (rules, skills, OAuth MCP)\n│ ├── vscode/ VS Code sidebar extension\n│ ├── openclaw-plugin/ OpenClaw native memory plugin (TypeScript)\n│ ├── opencode-plugin/ OpenCode native memory plugin (TypeScript)\n│ ├── cursor/ Cursor MCP setup guide\n│ ├── cline/ Cline MCP setup guide\n│ ├── windsurf/ Windsurf MCP setup guide\n│ ├── continue/ Continue MCP setup guide\n│ ├── vscode-copilot/ VS Code Copilot Chat MCP setup guide\n│ ├── langchain/ LangChain/LangGraph Python (PensyveStore + legacy PensyveMemory)\n│ ├── langchain-ts/ LangChain.js/LangGraph.js TypeScript (PensyveStore)\n│ ├── crewai/ CrewAI (PensyveStorage + standalone PensyveCrewMemory)\n│ └── autogen/ Microsoft AutoGen multi-agent memory\n├── tests/python/ Python integration tests\n├── benchmarks/ LongMemEval_S evaluation + weight tuning\n├── website/ Astro + Tailwind static site for pensyve.com\n└── docs/ Architecture, roadmap, design specs, implementation plans\n```\n\n## Development\n\n### First-Time Setup\n\n```bash\n# Install dependencies (creates .venv automatically)\nuv sync --extra dev\n\n# Build the native Python module (required before running any Python code)\nuv run maturin develop --release -m pensyve-python/Cargo.toml\n\n# Verify the module loads\nuv run python -c \"import pensyve; print(pensyve.__version__)\"\n```\n\n> **Note:** The `pensyve` Python package is a native Rust extension built with PyO3.\n> You must run `uv run maturin develop` before `pytest` or any Python import of `pensyve`,\n> otherwise you will get `ModuleNotFoundError: No module named 'pensyve'`.\n\n### Build & Test\n\n```bash\nmake build # Compile Rust + build PyO3 module\nmake test # Run all tests (Rust + Python)\nmake lint # clippy + ruff + pyright\nmake format # cargo fmt + ruff format\nmake check # lint + test (CI gate)\n```\n\nTo run test suites individually:\n\n```bash\ncargo test --workspace # Rust tests\nuv run maturin develop --release -m pensyve-python/Cargo.toml # Build PyO3 module first\nuv run pytest tests/python/ -v # Python tests\ncd pensyve-ts && bun test # TypeScript tests\ncd pensyve-go && go test ./... # Go tests\n```\n\n### Additional SDKs\n\n```bash\ncd pensyve-ts && bun test # TypeScript (38 tests)\ncd pensyve-go && go test ./... # Go (17 tests)\ncd pensyve-wasm && cargo check # WASM (standalone)\n```\n\n### Benchmarks\n\n```bash\n# Synthetic recall smoke test (planted facts, no external dataset required)\npython benchmarks/synthetic/run.py --generate --evaluate --verbose\n```\n\n## Competitive Landscape\n\n| What you need | Pensyve | Mem0 | Zep | Honcho |\n| -------------------------------- | ------------------------------------------------------------- | ------------------- | -------------------- | -------------- |\n| Works offline, no cloud required | **Yes** — SQLite, runs on your laptop | No — cloud API | No — requires server | No — cloud API |\n| Agent learns from outcomes | **Yes** — procedural memory tracks what works | No | No | No |\n| Finds memories by meaning | **8-signal fusion** (vector + BM25 + graph + intent + 4 more) | Vector only | Vector + temporal | Vector only |\n| Memories fade naturally | **FSRS forgetting curve** with reinforcement | No — manual cleanup | Basic TTL | No |\n| Multi-turn conversation capture | **Episodes** with outcome tracking | Basic | Yes | Yes |\n| Framework agnostic | **Python, TypeScript, Go, MCP, REST, CLI** | Python SDK | Python/JS | Python |\n| Claude Code / Cursor / VS Code | **Native plugins + MCP** | No | No | No |\n| Production-ready at scale | **Postgres + pgvector** (feature-gated) | Yes | Yes | Yes |\n| Open source | **Apache 2.0** | Yes | Partial | Yes |\n\n## License\n\n[Apache 2.0](LICENSE)\n",
"bytes": 23023,
"sha": "690058a9eb78fd508c05c000747c8b1ef743a62c4c1cc04c35165ab2cf8e25e0",
"repo_slug": "major7apps/pensyve",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_major7apps_pensyve_2245bae7/readme"
}