aakash-kr-7/meno

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.