# aakash-kr-7/meno architecture

> Architecture diagram of the GitHub repository aakash-kr-7/meno, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aakash-kr-7/meno
- Repository: https://github.com/aakash-kr-7/meno

## Overview

1. **What MENO is architecturally**
   MENO is a persistence layer for “memory” that sits between short-lived conversation state and long-lived repository knowledge. The repo is organized as a multi-service platform: a FastAPI backend, a background promotion worker, an MCP server, a CLI, and a Python SDK, all centered on shared knowledge and session models.

2. **Primary runtime entrypoints**
   The main server lives in `apps/api/main.py` and exposes the HTTP API. A separate background process in `apps/worker/promotion_worker.py` handles session-to-knowledge promotion. `apps/mcp/server.py` provides a Model Context Protocol integration for external AI tools. The CLI is under `cli/meno_cli`, and the public SDK is under `sdk/python/meno`.

3. **Core storage boundary**
   The system uses PostgreSQL as the canonical datastore, with Alembic migrations under `db/migrations` and ORM models in `db/models`. The main persisted entities are:
   - sessions and messages
   - contexts
   - knowledge objects
   - relationships between knowledge objects
   - profile metadata
   Redis is used separately for working memory, through `memory/working/redis_store.py`.

4. **Tiered memory model**
   The README’s tiering maps directly to the codebase’s responsibilities:
   - **Tier 0**: working memory for active sessions and recent messages
   - **Tier 1**: stored knowledge objects with vector search
   - **Tier 2**: relationship graph over knowledge objects
   - **Tier 3**: behavioral/profile metadata
   This is the main architectural separation to capture in a diagram.

5. **Session and working-memory flow**
   Session APIs in `apps/api/routes/sessions.py` write conversational state into the working-memory layer and session tables. That data is intentionally temporary: it supports active interactions, can be fetched as history, and can later be expired or deleted. The session subsystem is the source of material that may later be promoted into durable knowledge.

6. **Knowledge lifecycle**
   Knowledge creation and access are handled in `apps/api/routes/knowledge.py` and the `knowledge/` package. The flow is: ingest typed content, store it as a knowledge object, optionally scope it to contexts, and later retrieve it semantically or structurally. Knowledge types include decisions, architectures, API specs, code patterns, bug reports, and memory, with decay behavior varying by type.

7. **Context and graph boundaries**
   Contexts are first-class scoping entities in `apps/api/routes/context.py` and `knowledge/context.py`. They let knowledge be attached to projects, teams, or other namespaces. Relationships are modeled explicitly in `db/models/relationship.py` and managed by `knowledge/relationships.py`, enabling graph traversal and typed edges between objects instead of purely vector-based lookup.

8. **Retrieval and ranking pipeline**
   Retrieval is not just vector similarity. `knowledge/retrieval.py` performs semantic lookup against pgvector-backed embeddings, then `core/ranking.py` applies time-decay re-ranking based on knowledge type and age. `core/embeddings.py` and `core/llm.py` support the extraction and embedding side of this pipeline. The result is a hybrid retrieval path: vector search plus type-aware relevance adjustment.

9. **Promotion worker**
   The worker service is the bridge from transient session data to durable knowledge. It scans eligible inactive sessions, extracts structured knowledge, and persists promoted items. This is exposed through worker routes in `apps/api/routes/worker.py` and the standalone worker entrypoint. In diagram terms, it is the asynchronous pipeline that turns conversations into long-term memory.

10. **Security and configuration**
    Authentication is centralized in `core/auth.py` and enforced through API middleware in `apps/api/middleware/auth.py`. `core/config.py` holds environment-driven settings used across services. This means the API, worker, and MCP components share a common configuration and auth model rather than each owning their own.

11. **Client access paths**
    There are two main client surfaces:
    - the **Python SDK** in `sdk/python/meno`, which talks to the HTTP API for programmatic storage, retrieval, context definition, and relationship management
    - the **CLI** in `cli/meno_cli`, which provides local workflow commands like init, capture, ingest, status, and hooks
    These are not separate data stores; they are alternate entrypoints into the same backend system.

12. **Operational and integration tooling**
    The repo includes Docker Compose for local PostgreSQL/Redis orchestration, a `Dockerfile` for containerization, examples under `examples/`, and tests that cover API, store, retrieval, ranking, relationships, sessions, SDK, and MCP behavior. The architecture is therefore designed for local-first development but with clear service boundaries suitable for deployment as a small distributed system.

Main entry points: [`apps/api/main.py`](https://github.com/aakash-kr-7/meno/blob/main/apps/api/main.py) (API server), [`db/session.py`](https://github.com/aakash-kr-7/meno/blob/main/db/session.py) (PostgreSQL), [`apps/worker/promotion_worker.py`](https://github.com/aakash-kr-7/meno/blob/main/apps/worker/promotion_worker.py) (Promotion worker), [`apps/api/routes/sessions.py`](https://github.com/aakash-kr-7/meno/blob/main/apps/api/routes/sessions.py) (Sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_services["Runtime services"]
  node_api["API server<br/>FastAPI app<br/>[main.py]"]
  node_worker["Promotion worker<br/>async worker"]
  node_mcp["MCP server<br/>tool server<br/>[server.py]"]
end

subgraph group_memory["Memory model"]
  node_sessions["Sessions<br/>tier 0 state<br/>[sessions.py]"]
  node_working[("Working memory<br/>redis-backed tier 0<br/>[redis_store.py]")]
  node_knowledge[("Knowledge objects<br/>tier 1 store<br/>[store.py]")]
  node_retrieval{{"Retrieval<br/>hybrid search<br/>[retrieval.py]"}}
  node_relationships(("Relationships<br/>tier 2 graph<br/>[relationships.py]"))
  node_profiles["Profiles<br/>tier 3 metadata<br/>[profiles.py]"]
  node_contexts["Contexts<br/>scoping layer<br/>[context.py]"]
  node_ingest{{"Extraction<br/>promotion logic<br/>[extraction.py]"}}
end

subgraph group_clients["Client surfaces"]
  node_cli["CLI<br/>command line<br/>[main.py]"]
  node_sdk["Python SDK<br/>client library<br/>[client.py]"]
end

subgraph group_storage["Storage layer"]
  node_db[("PostgreSQL<br/>canonical datastore<br/>[session.py]")]
  node_migrations["Migrations<br/>schema evolution"]
  node_models["ORM models<br/>persistence models"]
end

subgraph group_platform["Core platform"]
  node_auth{{"Auth<br/>security boundary<br/>[auth.py]"}}
  node_config["Config<br/>shared settings<br/>[config.py]"]
  node_embeddings{{"Embeddings<br/>LLM support<br/>[embeddings.py]"}}
  node_ranking{{"Ranking<br/>relevance scoring<br/>[ranking.py]"}}
end

node_cli -->|"uses"| node_api
node_sdk -->|"uses"| node_api
node_mcp -->|"bridges"| node_api
node_api -->|"manages"| node_sessions
node_api -->|"manages"| node_knowledge
node_api -->|"manages"| node_contexts
node_api -->|"manages"| node_relationships
node_api -->|"manages"| node_profiles
node_sessions -->|"stores"| node_working
node_sessions -->|"persists"| node_db
node_knowledge -->|"persists"| node_db
node_relationships -->|"persists"| node_db
node_contexts -->|"persists"| node_db
node_profiles -->|"persists"| node_db
node_migrations -->|"evolves"| node_db
node_models -->|"maps"| node_db
node_retrieval -->|"uses"| node_embeddings
node_retrieval -->|"uses"| node_ranking
node_retrieval -->|"reads"| node_knowledge
node_worker -->|"extracts"| node_ingest
node_worker -->|"scans"| node_sessions
node_worker -->|"promotes"| node_knowledge
node_api -->|"enforces"| node_auth
node_mcp -->|"enforces"| node_auth
node_api -->|"reads"| node_config
node_worker -->|"reads"| node_config
node_mcp -->|"reads"| node_config

click node_api "https://github.com/aakash-kr-7/meno/blob/main/apps/api/main.py"
click node_worker "https://github.com/aakash-kr-7/meno/blob/main/apps/worker/promotion_worker.py"
click node_mcp "https://github.com/aakash-kr-7/meno/blob/main/apps/mcp/server.py"
click node_cli "https://github.com/aakash-kr-7/meno/blob/main/cli/meno_cli/main.py"
click node_sdk "https://github.com/aakash-kr-7/meno/blob/main/sdk/python/meno/client.py"
click node_sessions "https://github.com/aakash-kr-7/meno/blob/main/apps/api/routes/sessions.py"
click node_working "https://github.com/aakash-kr-7/meno/blob/main/memory/working/redis_store.py"
click node_knowledge "https://github.com/aakash-kr-7/meno/blob/main/knowledge/store.py"
click node_retrieval "https://github.com/aakash-kr-7/meno/blob/main/knowledge/retrieval.py"
click node_relationships "https://github.com/aakash-kr-7/meno/blob/main/knowledge/relationships.py"
click node_profiles "https://github.com/aakash-kr-7/meno/blob/main/apps/api/routes/profiles.py"
click node_contexts "https://github.com/aakash-kr-7/meno/blob/main/knowledge/context.py"
click node_ingest "https://github.com/aakash-kr-7/meno/blob/main/knowledge/extraction.py"
click node_db "https://github.com/aakash-kr-7/meno/blob/main/db/session.py"
click node_migrations "https://github.com/aakash-kr-7/meno/blob/main/db/migrations/versions/332a4d6876d7_knowledge_intelligence_schema.py"
click node_models "https://github.com/aakash-kr-7/meno/blob/main/db/models/knowledge_object.py"
click node_auth "https://github.com/aakash-kr-7/meno/blob/main/core/auth.py"
click node_config "https://github.com/aakash-kr-7/meno/blob/main/core/config.py"
click node_embeddings "https://github.com/aakash-kr-7/meno/blob/main/core/embeddings.py"
click node_ranking "https://github.com/aakash-kr-7/meno/blob/main/core/ranking.py"

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_api,node_worker,node_mcp toneBlue
class node_sessions,node_working,node_knowledge,node_retrieval,node_relationships,node_profiles,node_contexts,node_ingest toneAmber
class node_cli,node_sdk toneMint
class node_db,node_migrations,node_models toneRose
class node_auth,node_config,node_embeddings,node_ranking toneIndigo
```

## Components

### Runtime services

Primary entrypoints that expose or execute the system

- [API server](https://github.com/aakash-kr-7/meno/blob/main/apps/api/main.py): FastAPI app · HTTP entrypoint for sessions, knowledge, contexts, profiles, and relationships · `apps/api/main.py`
- [Promotion worker](https://github.com/aakash-kr-7/meno/blob/main/apps/worker/promotion_worker.py): async worker · Background process that promotes session data into durable knowledge · `apps/worker/promotion_worker.py`
- [MCP server](https://github.com/aakash-kr-7/meno/blob/main/apps/mcp/server.py): tool server · Model Context Protocol integration for external AI tools · `apps/mcp/server.py`

### Memory model

Tiered persistence and retrieval boundaries

- [Sessions](https://github.com/aakash-kr-7/meno/blob/main/apps/api/routes/sessions.py): tier 0 state · Active conversation state and recent messages · `apps/api/routes/sessions.py`
- [Working memory](https://github.com/aakash-kr-7/meno/blob/main/memory/working/redis_store.py): redis-backed tier 0 · Ephemeral Redis store for short-lived session memory · `memory/working/redis_store.py`
- [Knowledge objects](https://github.com/aakash-kr-7/meno/blob/main/knowledge/store.py): tier 1 store · Durable typed knowledge with vector search and decay-aware access · `knowledge/store.py`
- [Retrieval](https://github.com/aakash-kr-7/meno/blob/main/knowledge/retrieval.py): hybrid search · Semantic lookup over embeddings with ranking and re-scoring · `knowledge/retrieval.py`
- [Relationships](https://github.com/aakash-kr-7/meno/blob/main/knowledge/relationships.py): tier 2 graph · Typed edges and graph traversal between knowledge objects · `knowledge/relationships.py`
- [Profiles](https://github.com/aakash-kr-7/meno/blob/main/apps/api/routes/profiles.py): tier 3 metadata · Behavioral and profile metadata stored alongside memory · `apps/api/routes/profiles.py`
- [Contexts](https://github.com/aakash-kr-7/meno/blob/main/knowledge/context.py): scoping layer · Project, team, or namespace boundaries for knowledge · `knowledge/context.py`
- [Extraction](https://github.com/aakash-kr-7/meno/blob/main/knowledge/extraction.py): promotion logic · Structured extraction of knowledge from conversation and input content · `knowledge/extraction.py`

### Client surfaces

External ways to use the platform

- [CLI](https://github.com/aakash-kr-7/meno/blob/main/cli/meno_cli/main.py): command line · Local workflow commands for capture, ingest, init, status, and hooks · `cli/meno_cli/main.py`
- [Python SDK](https://github.com/aakash-kr-7/meno/blob/main/sdk/python/meno/client.py): client library · Programmatic client for the HTTP API · `sdk/python/meno/client.py`

### Storage layer

Canonical datastore and supporting persistence

- [PostgreSQL](https://github.com/aakash-kr-7/meno/blob/main/db/session.py): canonical datastore · Primary relational store for sessions, knowledge, contexts, relationships, and profiles · `db/session.py`
- [Migrations](https://github.com/aakash-kr-7/meno/blob/main/db/migrations/versions/332a4d6876d7_knowledge_intelligence_schema.py): schema evolution · Alembic schema history for the database · `db/migrations/versions/332a4d6876d7_knowledge_intelligence_schema.py`
- [ORM models](https://github.com/aakash-kr-7/meno/blob/main/db/models/knowledge_object.py): persistence models · Database entity definitions for core persisted records · `db/models/knowledge_object.py`

### Core platform

Shared cross-cutting logic used by all runtimes

- [Auth](https://github.com/aakash-kr-7/meno/blob/main/core/auth.py): security boundary · Shared authentication and API middleware · `core/auth.py`
- [Config](https://github.com/aakash-kr-7/meno/blob/main/core/config.py): shared settings · Environment-driven configuration used across services · `core/config.py`
- [Embeddings](https://github.com/aakash-kr-7/meno/blob/main/core/embeddings.py): LLM support · Embedding generation and model helpers for semantic retrieval · `core/embeddings.py`
- [Ranking](https://github.com/aakash-kr-7/meno/blob/main/core/ranking.py): relevance scoring · Type-aware and age-aware reranking for retrieved knowledge · `core/ranking.py`

## Connections

- CLI → API server: uses · CLI commands call the backend API
- Python SDK → API server: uses · Python client communicates with the HTTP API
- MCP server → API server: bridges · MCP service exposes repository memory through the API
- API server → Sessions: manages · Session routes write and read conversational state
- API server → Knowledge objects: manages · Knowledge routes create, retrieve, and scope durable memory
- API server → Contexts: manages · Context routes define knowledge namespaces
- API server → Relationships: manages · Relationship routes create typed graph links
- API server → Profiles: manages · Profile routes persist tier 3 metadata
- Sessions → Working memory: stores · Active session state is kept in Redis-backed working memory
- Sessions → PostgreSQL: persists · Session records are also stored in PostgreSQL
- Knowledge objects → PostgreSQL: persists · Knowledge objects live in the canonical database
- Relationships → PostgreSQL: persists · Relationship edges are stored relationally
- Contexts → PostgreSQL: persists · Context definitions are stored in PostgreSQL
- Profiles → PostgreSQL: persists · Profile metadata is stored in PostgreSQL
- Migrations → PostgreSQL: evolves · Alembic migrations evolve the schema
- ORM models → PostgreSQL: maps · ORM models define the persistent schema boundary
- Retrieval → Embeddings: uses · Retrieval depends on embedding generation and vector lookup
- Retrieval → Ranking: uses · Semantic results are reranked by relevance and decay
- Retrieval → Knowledge objects: reads · Search operates over stored knowledge objects
- Promotion worker → Extraction: extracts · Promotion worker turns sessions into structured knowledge
- Promotion worker → Sessions: scans · Worker inspects inactive sessions for promotion candidates
- Promotion worker → Knowledge objects: promotes · Promoted items are persisted as durable knowledge
- API server → Auth: enforces · API middleware applies shared authentication
- MCP server → Auth: enforces · MCP server uses the shared auth model
- API server → Config: reads · API services use shared configuration
- Promotion worker → Config: reads · Worker process uses shared configuration
- MCP server → Config: reads · MCP server uses shared configuration