# guttedgarden/orna architecture

> Architecture diagram of the GitHub repository guttedgarden/orna, 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/guttedgarden/orna
- Repository: https://github.com/guttedgarden/orna

## Overview

Orna Memory is a self-hosted MCP backend for durable, project-scoped agent memory. An AI client authenticates to the stateless HTTP MCP endpoint and supplies project context, then searches, retrieves a revision, or adds validated experience. Search prepares dense and lexical queries, retrieves candidates in parallel, fuses rankings, and returns a sanitized result; writes scan for secrets, enforce the embedding token limit, prepare content, embed it, and persist an immutable revision. The graph follows documented capabilities and sampled service/repository calls; unsampled write-service wiring is shown only where the README establishes it.

Main entry points: [`orna-memory-mcp/app/mcp_server.py`](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/mcp_server.py) (MCP server), [`orna-memory-mcp/app/write.py`](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/write.py) (Memory write), [`orna-memory-mcp/app/search.py`](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/search.py) (Search service), [`orna-memory-mcp/app/repository.py`](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/repository.py) (Memory repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP interface"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_auth["Bearer auth<br/>[auth.py]"]
  node_project["Project context<br/>[project_context.py]"]
end

subgraph group_memory["Memory operations"]
  node_write["Memory write<br/>[write.py]"]
  node_safety["Write safety<br/>[write_safety.py]"]
  node_normalizer["Content normalizer<br/>[normalizer.py]"]
  node_get["Revision lookup<br/>[repository.py]"]
end

subgraph group_retrieval["Hybrid retrieval"]
  node_search["Search service<br/>[search.py]"]
  node_embeddings["Embedding service<br/>[embeddings.py]"]
  node_profile["Embedding profile"]
end

subgraph group_storage["Persistence"]
  node_repository["Memory repository<br/>[repository.py]"]
  node_postgres[("PostgreSQL + pgvector")]
end

node_client(("AI client"))

node_client -->|"calls MCP tools"| node_mcp
node_mcp -->|"verifies bearer"| node_auth
node_mcp -->|"resolves project"| node_project
node_mcp -->|"dispatches add"| node_write
node_mcp -->|"dispatches search"| node_search
node_mcp -->|"reads revision"| node_repository
node_write -->|"validates input"| node_safety
node_write -->|"prepares content"| node_normalizer
node_write -->|"embeds memory"| node_embeddings
node_write -->|"inserts revision"| node_repository
node_search -->|"normalizes query"| node_normalizer
node_search -->|"embeds query"| node_embeddings
node_search -->|"retrieves candidates"| node_repository
node_repository -->|"reads and writes"| node_postgres
node_embeddings -->|"uses profile"| node_profile

click node_mcp "https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/mcp_server.py"
click node_auth "https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/auth.py"
click node_project "https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/project_context.py"
click node_write "https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/write.py"
click node_safety "https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/write_safety.py"
click node_normalizer "https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/normalizer.py"
click node_get "https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/repository.py"
click node_search "https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/search.py"
click node_embeddings "https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/embeddings.py"
click node_profile "https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/embedding_profile.py"
click node_repository "https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/repository.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_mcp,node_auth,node_project,node_client toneBlue
class node_write,node_safety,node_normalizer,node_get toneAmber
class node_search,node_embeddings,node_profile toneMint
class node_repository,node_postgres toneRose
```

## Components

### MCP interface

- [MCP server](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/mcp_server.py): `orna-memory-mcp/app/mcp_server.py`
- [Bearer auth](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/auth.py): `orna-memory-mcp/app/auth.py`
- [Project context](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/project_context.py): `orna-memory-mcp/app/project_context.py`

### Memory operations

- [Memory write](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/write.py): `orna-memory-mcp/app/write.py`
- [Write safety](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/write_safety.py): `orna-memory-mcp/app/write_safety.py`
- [Content normalizer](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/normalizer.py): `orna-memory-mcp/app/normalizer.py`
- [Revision lookup](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/repository.py): `orna-memory-mcp/app/repository.py`

### Hybrid retrieval

- [Search service](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/search.py): `orna-memory-mcp/app/search.py`
- [Embedding service](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/embeddings.py): `orna-memory-mcp/app/embeddings.py`
- [Embedding profile](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/embedding_profile.py): `orna-memory-mcp/app/embedding_profile.py`

### Persistence

- [Memory repository](https://github.com/guttedgarden/orna/blob/main/orna-memory-mcp/app/repository.py): `orna-memory-mcp/app/repository.py`
- **PostgreSQL + pgvector**

### Other components

- **AI client**

## Connections

- AI client → MCP server: calls MCP tools
- MCP server → Bearer auth: verifies bearer
- MCP server → Project context: resolves project
- MCP server → Memory write: dispatches add
- MCP server → Search service: dispatches search
- MCP server → Memory repository: reads revision
- Memory write → Write safety: validates input
- Memory write → Content normalizer: prepares content
- Memory write → Embedding service: embeds memory
- Memory write → Memory repository: inserts revision
- Search service → Content normalizer: normalizes query
- Search service → Embedding service: embeds query
- Search service → Memory repository: retrieves candidates
- Memory repository → PostgreSQL + pgvector: reads and writes
- Embedding service → Embedding profile: uses profile