# major7apps/pensyve architecture

> Architecture diagram of the GitHub repository major7apps/pensyve, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/major7apps/pensyve
- Repository: https://github.com/major7apps/pensyve

## Overview

Pensyve is an offline-first, cross-framework memory runtime for AI agents. Agents record episodes or explicit facts; the runtime stores episodic, semantic, and procedural memories, consolidates them, and retrieves ranked context for later sessions. Users reach the core through an in-process Python binding, remote REST/MCP interfaces and SDKs, or framework adapters. The core also supports SQLite/Postgres, embeddings, graph-assisted retrieval, forgetting, and feedback. README capabilities inform the map; several subsystem links use documented behavior because their source was not sampled.

Main entry points: [`pensyve-core/src/retrieval/engine.rs`](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/retrieval/engine.rs) (Recall engine), [`pensyve-core/src/types.rs`](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/types.rs) (Memory types), [`pensyve-mcp-gateway/src/main.rs`](https://github.com/major7apps/pensyve/blob/main/pensyve-mcp-gateway/src/main.rs) (HTTP gateway), [`pensyve-ts/src/index.ts`](https://github.com/major7apps/pensyve/blob/main/pensyve-ts/src/index.ts) (TS and Go SDKs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_framework_adapters["Framework adapters"]
  node_python_sdk["Python SDK"]
  node_native_binding["Native binding<br/>[lib.rs]"]
  node_remote_sdks["TS and Go SDKs<br/>[index.ts]"]
  node_cli["CLI<br/>[main.rs]"]
end

subgraph group_service["Service access"]
  node_mcp_server["MCP server<br/>[main.rs]"]
  node_mcp_tools["MCP tools<br/>[server.rs]"]
  node_gateway["HTTP gateway<br/>[main.rs]"]
  node_rest_api["REST API<br/>[rest.rs]"]
end

subgraph group_memory["Memory lifecycle"]
  node_episode_capture["Episode capture<br/>[observation.rs]"]
  node_extraction["Fact extraction<br/>[mod.rs]"]
  node_memory_types["Memory types<br/>[types.rs]"]
  node_consolidation["Consolidation<br/>[mod.rs]"]
  node_procedural["Procedural learning<br/>[procedural.rs]"]
  node_forgetting["Forgetting<br/>[decay.rs]"]
end

subgraph group_retrieval["Recall engine"]
  node_recall_engine["Recall engine<br/>[engine.rs]"]
  node_query_routing["Query routing"]
  node_grouped_recall["Grouped recall<br/>[recall_grouped.rs]"]
end

subgraph group_persistence["State and models"]
  node_sqlite[("SQLite store<br/>[sqlite.rs]")]
  node_postgres[("Postgres store<br/>[postgres.rs]")]
  node_embeddings["Embedding model<br/>[embedding.rs]"]
  node_graph_index[("Knowledge graph<br/>[graph.rs]")]
end

node_agent(("AI agent"))

node_agent -->|"uses adapter"| node_framework_adapters
node_framework_adapters -->|"captures and calls"| node_remote_sdks
node_agent -->|"records and recalls"| node_python_sdk
node_python_sdk -->|"calls in-process"| node_native_binding
node_agent -->|"calls API"| node_remote_sdks
node_agent -->|"runs commands"| node_cli
node_cli -->|"requests recall"| node_recall_engine
node_remote_sdks -->|"sends requests"| node_gateway
node_gateway -->|"dispatches REST"| node_rest_api
node_gateway -->|"serves MCP"| node_mcp_tools
node_mcp_server -->|"exposes tools"| node_mcp_tools
node_mcp_tools -->|"records and manages"| node_memory_types
node_native_binding -->|"records and recalls"| node_memory_types
node_memory_types -->|"forms episodes"| node_episode_capture
node_episode_capture -->|"extracts facts"| node_extraction
node_extraction -->|"produces memories"| node_memory_types
node_memory_types -->|"persists memories"| node_sqlite
node_memory_types -->|"tracks outcomes"| node_procedural
node_consolidation -->|"promotes and updates"| node_sqlite
node_consolidation -->|"applies decay"| node_forgetting
node_recall_engine -->|"classifies query"| node_query_routing
node_recall_engine -->|"gathers candidates"| node_sqlite
node_recall_engine -->|"embeds query"| node_embeddings
node_recall_engine -->|"uses graph signal"| node_graph_index
node_recall_engine -->|"retrieves learned actions"| node_procedural
node_grouped_recall -->|"requests recall"| node_recall_engine
node_recall_engine -->|"returns ranked context"| node_agent
node_postgres -.->|"stores production memories"| node_recall_engine

click node_framework_adapters "https://github.com/major7apps/pensyve/tree/main/integrations"
click node_python_sdk "https://github.com/major7apps/pensyve/tree/main/pensyve-python/python/pensyve"
click node_native_binding "https://github.com/major7apps/pensyve/blob/main/pensyve-python/src/lib.rs"
click node_remote_sdks "https://github.com/major7apps/pensyve/blob/main/pensyve-ts/src/index.ts"
click node_cli "https://github.com/major7apps/pensyve/blob/main/pensyve-cli/src/main.rs"
click node_mcp_server "https://github.com/major7apps/pensyve/blob/main/pensyve-mcp/src/main.rs"
click node_mcp_tools "https://github.com/major7apps/pensyve/blob/main/pensyve-mcp-tools/src/server.rs"
click node_gateway "https://github.com/major7apps/pensyve/blob/main/pensyve-mcp-gateway/src/main.rs"
click node_rest_api "https://github.com/major7apps/pensyve/blob/main/pensyve-mcp-gateway/src/rest.rs"
click node_episode_capture "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/observation.rs"
click node_extraction "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/extraction/mod.rs"
click node_memory_types "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/types.rs"
click node_consolidation "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/consolidation/mod.rs"
click node_procedural "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/procedural.rs"
click node_forgetting "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/decay.rs"
click node_recall_engine "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/retrieval/engine.rs"
click node_query_routing "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/retrieval/query_classifier.rs"
click node_grouped_recall "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/recall_grouped.rs"
click node_sqlite "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/storage/sqlite.rs"
click node_postgres "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/storage/postgres.rs"
click node_embeddings "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/embedding.rs"
click node_graph_index "https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/graph.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_framework_adapters,node_python_sdk,node_native_binding,node_remote_sdks,node_cli toneBlue
class node_mcp_server,node_mcp_tools,node_gateway,node_rest_api toneAmber
class node_episode_capture,node_extraction,node_memory_types,node_consolidation,node_procedural,node_forgetting toneMint
class node_recall_engine,node_query_routing,node_grouped_recall toneRose
class node_sqlite,node_postgres,node_embeddings,node_graph_index,node_agent toneIndigo
```

## Components

### Agent interfaces

- [Framework adapters](https://github.com/major7apps/pensyve/tree/main/integrations): `integrations`
- [Python SDK](https://github.com/major7apps/pensyve/tree/main/pensyve-python/python/pensyve): `pensyve-python/python/pensyve`
- [Native binding](https://github.com/major7apps/pensyve/blob/main/pensyve-python/src/lib.rs): `pensyve-python/src/lib.rs`
- [TS and Go SDKs](https://github.com/major7apps/pensyve/blob/main/pensyve-ts/src/index.ts): `pensyve-ts/src/index.ts`
- [CLI](https://github.com/major7apps/pensyve/blob/main/pensyve-cli/src/main.rs): `pensyve-cli/src/main.rs`

### Service access

- [MCP server](https://github.com/major7apps/pensyve/blob/main/pensyve-mcp/src/main.rs): `pensyve-mcp/src/main.rs`
- [MCP tools](https://github.com/major7apps/pensyve/blob/main/pensyve-mcp-tools/src/server.rs): `pensyve-mcp-tools/src/server.rs`
- [HTTP gateway](https://github.com/major7apps/pensyve/blob/main/pensyve-mcp-gateway/src/main.rs): `pensyve-mcp-gateway/src/main.rs`
- [REST API](https://github.com/major7apps/pensyve/blob/main/pensyve-mcp-gateway/src/rest.rs): `pensyve-mcp-gateway/src/rest.rs`

### Memory lifecycle

- [Episode capture](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/observation.rs): `pensyve-core/src/observation.rs`
- [Fact extraction](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/extraction/mod.rs): `pensyve-core/src/extraction/mod.rs`
- [Memory types](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/types.rs): `pensyve-core/src/types.rs`
- [Consolidation](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/consolidation/mod.rs): `pensyve-core/src/consolidation/mod.rs`
- [Procedural learning](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/procedural.rs): `pensyve-core/src/procedural.rs`
- [Forgetting](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/decay.rs): `pensyve-core/src/decay.rs`

### Recall engine

- [Recall engine](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/retrieval/engine.rs): `pensyve-core/src/retrieval/engine.rs`
- [Query routing](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/retrieval/query_classifier.rs): `pensyve-core/src/retrieval/query_classifier.rs`
- [Grouped recall](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/recall_grouped.rs): `pensyve-core/src/recall_grouped.rs`

### State and models

- [SQLite store](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/storage/sqlite.rs): `pensyve-core/src/storage/sqlite.rs`
- [Postgres store](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/storage/postgres.rs): `pensyve-core/src/storage/postgres.rs`
- [Embedding model](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/embedding.rs): `pensyve-core/src/embedding.rs`
- [Knowledge graph](https://github.com/major7apps/pensyve/blob/main/pensyve-core/src/graph.rs): `pensyve-core/src/graph.rs`

### Other components

- **AI agent**

## Connections

- AI agent → Framework adapters: uses adapter
- Framework adapters → TS and Go SDKs: captures and calls
- AI agent → Python SDK: records and recalls
- Python SDK → Native binding: calls in-process
- AI agent → TS and Go SDKs: calls API
- AI agent → CLI: runs commands
- CLI → Recall engine: requests recall
- TS and Go SDKs → HTTP gateway: sends requests
- HTTP gateway → REST API: dispatches REST
- HTTP gateway → MCP tools: serves MCP
- MCP server → MCP tools: exposes tools
- MCP tools → Memory types: records and manages
- Native binding → Memory types: records and recalls
- Memory types → Episode capture: forms episodes
- Episode capture → Fact extraction: extracts facts
- Fact extraction → Memory types: produces memories
- Memory types → SQLite store: persists memories
- Memory types → Procedural learning: tracks outcomes
- Consolidation → SQLite store: promotes and updates
- Consolidation → Forgetting: applies decay
- Recall engine → Query routing: classifies query
- Recall engine → SQLite store: gathers candidates
- Recall engine → Embedding model: embeds query
- Recall engine → Knowledge graph: uses graph signal
- Recall engine → Procedural learning: retrieves learned actions
- Grouped recall → Recall engine: requests recall
- Recall engine → AI agent: returns ranked context
- Postgres store → Recall engine: stores production memories