# varun29ankus/shodh-memory architecture

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

- Interactive diagram: https://gitdiagram.com/varun29ankus/shodh-memory
- Repository: https://github.com/varun29ankus/shodh-memory

## Overview

Shodh-Memory is an offline persistent cognitive-memory service for agents and robots. The main workflow accepts a memory through HTTP, enriches it during ingestion, and stores it for later recall; the server also exposes MCP, Python-client, and Zenoh entry points. Memory management includes graph associations, local semantic models, tiered storage, and feedback-driven learning. The README documents these capabilities, while the source excerpts show selected routing, ingestion, state, and storage relationships; links to unsampled implementations are included only where documented.

Main entry points: [`src/memory/mod.rs`](https://github.com/varun29ankus/shodh-memory/blob/main/src/memory/mod.rs) (Memory system), [`src/handlers/router.rs`](https://github.com/varun29ankus/shodh-memory/blob/main/src/handlers/router.rs) (HTTP API), [`src/server.rs`](https://github.com/varun29ankus/shodh-memory/blob/main/src/server.rs) (Server runtime), [`src/ingest/mod.rs`](https://github.com/varun29ankus/shodh-memory/blob/main/src/ingest/mod.rs) (Experience ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Service interfaces"]
  node_http["HTTP API<br/>[router.rs]"]
  node_mcp["MCP tools<br/>[index.ts]"]
  node_python["Python client<br/>[client.py]"]
  node_zenoh["Zenoh transport<br/>[handlers.rs]"]
  node_ui["Dashboard<br/>[App.tsx]"]
end

subgraph group_memory["Memory lifecycle"]
  node_ingestion["Experience ingestion<br/>[mod.rs]"]
  node_memory_system["Memory system<br/>[mod.rs]"]
  node_storage[("Persistent storage<br/>[storage.rs]")]
  node_tiers["Memory tiers<br/>[types.rs]"]
  node_graph["Memory graph<br/>[graph_memory.rs]"]
  node_recall["Recall and retrieval<br/>[recall.rs]"]
end

subgraph group_intelligence["Local intelligence"]
  node_embedding["Local embeddings<br/>[minilm.rs]"]
  node_ner["Entity extraction<br/>[gliner.rs]"]
  node_relations["Typed relations<br/>[relation_typer.rs]"]
  node_learning["Feedback and decay<br/>[feedback.rs]"]
  node_reranking["Local reranking<br/>[cross_encoder.rs]"]
end

subgraph group_operations["State and operations"]
  node_server["Server runtime<br/>[server.rs]"]
  node_state["User state manager<br/>[state.rs]"]
  node_integrity["Integrity checks<br/>[integrity.rs]"]
  node_metrics["Operational metrics<br/>[metrics.rs]"]
end

node_agent(("Agent or robot"))

node_agent -->|"sends requests"| node_http
node_http -->|"routes writes"| node_ingestion
node_ingestion -->|"stores memory"| node_memory_system
node_memory_system -.->|"persists records"| node_storage
node_memory_system -.->|"uses tier model"| node_tiers
node_memory_system -.->|"builds associations"| node_graph
node_http -->|"routes recall"| node_recall
node_recall -.->|"retrieves memories"| node_memory_system
node_ingestion -->|"extracts entities"| node_ner
node_ingestion -.->|"types relations"| node_relations
node_memory_system -.->|"semantic search"| node_embedding
node_recall -.->|"reranks results"| node_reranking
node_learning -.->|"strengthens memories"| node_memory_system
node_server -.->|"starts routes"| node_http
node_server -.->|"initializes state"| node_state
node_server -->|"starts optionally"| node_zenoh
node_zenoh -.->|"handles memory operations"| node_memory_system
node_mcp -.->|"offers memory tools"| node_agent
node_python -.->|"calls service"| node_http
node_ui -.->|"uses API"| node_http
node_server -->|"runs integrity checks"| node_integrity
node_server -.->|"exposes metrics"| node_metrics

click node_http "https://github.com/varun29ankus/shodh-memory/blob/main/src/handlers/router.rs"
click node_mcp "https://github.com/varun29ankus/shodh-memory/blob/main/mcp-server/index.ts"
click node_python "https://github.com/varun29ankus/shodh-memory/blob/main/python/shodh_memory/client.py"
click node_zenoh "https://github.com/varun29ankus/shodh-memory/blob/main/src/zenoh_transport/handlers.rs"
click node_ingestion "https://github.com/varun29ankus/shodh-memory/blob/main/src/ingest/mod.rs"
click node_memory_system "https://github.com/varun29ankus/shodh-memory/blob/main/src/memory/mod.rs"
click node_storage "https://github.com/varun29ankus/shodh-memory/blob/main/src/memory/storage.rs"
click node_tiers "https://github.com/varun29ankus/shodh-memory/blob/main/src/memory/types.rs"
click node_graph "https://github.com/varun29ankus/shodh-memory/blob/main/src/graph_memory.rs"
click node_recall "https://github.com/varun29ankus/shodh-memory/blob/main/src/handlers/recall.rs"
click node_embedding "https://github.com/varun29ankus/shodh-memory/blob/main/src/embeddings/minilm.rs"
click node_ner "https://github.com/varun29ankus/shodh-memory/blob/main/src/embeddings/gliner.rs"
click node_relations "https://github.com/varun29ankus/shodh-memory/blob/main/src/relation_typer.rs"
click node_learning "https://github.com/varun29ankus/shodh-memory/blob/main/src/memory/feedback.rs"
click node_reranking "https://github.com/varun29ankus/shodh-memory/blob/main/src/embeddings/cross_encoder.rs"
click node_server "https://github.com/varun29ankus/shodh-memory/blob/main/src/server.rs"
click node_state "https://github.com/varun29ankus/shodh-memory/blob/main/src/handlers/state.rs"
click node_integrity "https://github.com/varun29ankus/shodh-memory/blob/main/src/integrity.rs"
click node_metrics "https://github.com/varun29ankus/shodh-memory/blob/main/src/metrics.rs"
click node_ui "https://github.com/varun29ankus/shodh-memory/blob/main/front/ui/src/app/App.tsx"

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_http,node_mcp,node_python,node_zenoh,node_ui toneBlue
class node_ingestion,node_memory_system,node_storage,node_tiers,node_graph,node_recall toneAmber
class node_embedding,node_ner,node_relations,node_learning,node_reranking toneMint
class node_server,node_state,node_integrity,node_metrics toneRose
class node_agent toneIndigo
```

## Components

### Service interfaces

- [HTTP API](https://github.com/varun29ankus/shodh-memory/blob/main/src/handlers/router.rs): `src/handlers/router.rs`
- [MCP tools](https://github.com/varun29ankus/shodh-memory/blob/main/mcp-server/index.ts): `mcp-server/index.ts`
- [Python client](https://github.com/varun29ankus/shodh-memory/blob/main/python/shodh_memory/client.py): `python/shodh_memory/client.py`
- [Zenoh transport](https://github.com/varun29ankus/shodh-memory/blob/main/src/zenoh_transport/handlers.rs): `src/zenoh_transport/handlers.rs`
- [Dashboard](https://github.com/varun29ankus/shodh-memory/blob/main/front/ui/src/app/App.tsx): `front/ui/src/app/App.tsx`

### Memory lifecycle

- [Experience ingestion](https://github.com/varun29ankus/shodh-memory/blob/main/src/ingest/mod.rs): `src/ingest/mod.rs`
- [Memory system](https://github.com/varun29ankus/shodh-memory/blob/main/src/memory/mod.rs): `src/memory/mod.rs`
- [Persistent storage](https://github.com/varun29ankus/shodh-memory/blob/main/src/memory/storage.rs): `src/memory/storage.rs`
- [Memory tiers](https://github.com/varun29ankus/shodh-memory/blob/main/src/memory/types.rs): `src/memory/types.rs`
- [Memory graph](https://github.com/varun29ankus/shodh-memory/blob/main/src/graph_memory.rs): `src/graph_memory.rs`
- [Recall and retrieval](https://github.com/varun29ankus/shodh-memory/blob/main/src/handlers/recall.rs): `src/handlers/recall.rs`

### Local intelligence

- [Local embeddings](https://github.com/varun29ankus/shodh-memory/blob/main/src/embeddings/minilm.rs): `src/embeddings/minilm.rs`
- [Entity extraction](https://github.com/varun29ankus/shodh-memory/blob/main/src/embeddings/gliner.rs): `src/embeddings/gliner.rs`
- [Typed relations](https://github.com/varun29ankus/shodh-memory/blob/main/src/relation_typer.rs): `src/relation_typer.rs`
- [Feedback and decay](https://github.com/varun29ankus/shodh-memory/blob/main/src/memory/feedback.rs): `src/memory/feedback.rs`
- [Local reranking](https://github.com/varun29ankus/shodh-memory/blob/main/src/embeddings/cross_encoder.rs): `src/embeddings/cross_encoder.rs`

### State and operations

- [Server runtime](https://github.com/varun29ankus/shodh-memory/blob/main/src/server.rs): `src/server.rs`
- [User state manager](https://github.com/varun29ankus/shodh-memory/blob/main/src/handlers/state.rs): `src/handlers/state.rs`
- [Integrity checks](https://github.com/varun29ankus/shodh-memory/blob/main/src/integrity.rs): `src/integrity.rs`
- [Operational metrics](https://github.com/varun29ankus/shodh-memory/blob/main/src/metrics.rs): `src/metrics.rs`

### Other components

- **Agent or robot**

## Connections

- Agent or robot → HTTP API: sends requests (evidence: `README.md`)
- HTTP API → Experience ingestion: routes writes (evidence: `src/handlers/router.rs`)
- Experience ingestion → Memory system: stores memory (evidence: `src/ingest/mod.rs`)
- Memory system → Persistent storage: persists records (evidence: `src/memory/storage.rs`)
- Memory system → Memory tiers: uses tier model (evidence: `README.md`)
- Memory system → Memory graph: builds associations (evidence: `README.md`)
- HTTP API → Recall and retrieval: routes recall (evidence: `src/handlers/router.rs`)
- Recall and retrieval → Memory system: retrieves memories (evidence: `README.md`)
- Experience ingestion → Entity extraction: extracts entities (evidence: `src/ingest/mod.rs`)
- Experience ingestion → Typed relations: types relations (evidence: `README.md`)
- Memory system → Local embeddings: semantic search (evidence: `README.md`)
- Recall and retrieval → Local reranking: reranks results (evidence: `README.md`)
- Feedback and decay → Memory system: strengthens memories (evidence: `README.md`)
- Server runtime → HTTP API: starts routes (evidence: `src/server.rs`)
- Server runtime → User state manager: initializes state (evidence: `src/server.rs`)
- Server runtime → Zenoh transport: starts optionally (evidence: `src/server.rs`)
- Zenoh transport → Memory system: handles memory operations (evidence: `src/zenoh_transport/handlers.rs`)
- MCP tools → Agent or robot: offers memory tools (evidence: `README.md`)
- Python client → HTTP API: calls service (evidence: `README.md`)
- Dashboard → HTTP API: uses API (evidence: `README.md`)
- Server runtime → Integrity checks: runs integrity checks (evidence: `src/server.rs`)
- Server runtime → Operational metrics: exposes metrics (evidence: `src/server.rs`)
