# theasthenosphere/samia architecture

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

- Interactive diagram: https://gitdiagram.com/theasthenosphere/samia
- Repository: https://github.com/theasthenosphere/samia

## Overview

SAM/IA is a local, biologically inspired persistent-memory system for AI agents and knowledge work. An agent invokes its MCP tools; recall combines episodic chainogram retrieval, fast hippocampal stores, and an optional semantic-fact arm into context, while write and consolidation paths preserve and refine memories. Autonomous maintenance runs decay and offline REM work, including fact extraction, contradiction handling, and integrity repair. The README documents these capabilities; sampled source confirms MCP delegation, retrieval behavior, and selected runtime wiring, so unsampled connections are kept conservative.

Main entry points: [`samia/mcp_server_main.py`](https://github.com/theasthenosphere/samia/blob/main/samia/mcp_server_main.py) (MCP server), [`samia/core/mcp_server/search.py`](https://github.com/theasthenosphere/samia/blob/main/samia/core/mcp_server/search.py) (Memory search), [`samia/core/context_extension/retrieval.py`](https://github.com/theasthenosphere/samia/blob/main/samia/core/context_extension/retrieval.py) (Chainogram retrieval), [`samia/runtime/maintenanced.py`](https://github.com/theasthenosphere/samia/blob/main/samia/runtime/maintenanced.py) (Maintenance daemon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Agent interface"]
  node_mcp["MCP server<br/>[mcp_server_main.py]"]
  node_search["Memory search<br/>[search.py]"]
  node_write["Memory writes<br/>[write.py]"]
  node_context_tools["Context tools<br/>[context_tools.py]"]
end

subgraph group_recall["Recall and context"]
  node_chainogram["Chainogram retrieval<br/>[retrieval.py]"]
  node_semantic["Semantic recall<br/>[semantic_recall.py]"]
  node_vector["Vector indexes<br/>[vector.py]"]
  node_hippocampus["Hippocampal fast store<br/>[__init__.py]"]
  node_entity["Entity bridges<br/>[entity_index.py]"]
end

subgraph group_memory["Memory lifecycle"]
  node_tier[("Tiered memory store<br/>[tier.py]")]
  node_chains[("Episodic chains<br/>[chain.py]")]
  node_hebbian[("Hebbian web<br/>[hebbian.py]")]
  node_consolidation["Consolidation<br/>[consolidation.py]"]
  node_fact_extract["Fact extraction<br/>[fact_extractor.py]"]
  node_integrity["Integrity repair<br/>[repair.py]"]
end

subgraph group_upkeep["Autonomous upkeep"]
  node_daemon["Maintenance daemon<br/>[maintenanced.py]"]
  node_rem["REM cycle<br/>[driver.py]"]
  node_contradiction["Contradiction checks<br/>[passes.py]"]
  node_inference["Local inference<br/>[inference.py]"]
  node_bio["Memory replay<br/>[replay.py]"]
end

node_agent(("AI agent"))

node_agent -->|"invokes tools"| node_mcp
node_mcp -->|"delegates search"| node_search
node_mcp -->|"delegates writes"| node_write
node_mcp -->|"delegates context"| node_context_tools
node_search -->|"queries indexes"| node_vector
node_search -->|"queries fast store"| node_hippocampus
node_search -->|"reads coactivation"| node_hebbian
node_context_tools -->|"retrieves chains"| node_chainogram
node_context_tools -.->|"composes facts"| node_semantic
node_chainogram -->|"reads chains"| node_chains
node_chainogram -->|"scores associations"| node_hebbian
node_chainogram -->|"queries bridges"| node_entity
node_write -->|"writes memories"| node_tier
node_consolidation -->|"consolidates store"| node_tier
node_consolidation -.->|"extracts facts"| node_fact_extract
node_daemon -->|"drives upkeep"| node_rem
node_rem -->|"runs offline work"| node_consolidation
node_rem -->|"sweeps candidates"| node_contradiction
node_contradiction -.->|"requests judgment"| node_inference
node_daemon -->|"runs replay"| node_bio
node_daemon -->|"runs repair"| node_integrity

click node_mcp "https://github.com/theasthenosphere/samia/blob/main/samia/mcp_server_main.py"
click node_search "https://github.com/theasthenosphere/samia/blob/main/samia/core/mcp_server/search.py"
click node_write "https://github.com/theasthenosphere/samia/blob/main/samia/core/mcp_server/write.py"
click node_context_tools "https://github.com/theasthenosphere/samia/blob/main/samia/core/mcp_server/context_tools.py"
click node_chainogram "https://github.com/theasthenosphere/samia/blob/main/samia/core/context_extension/retrieval.py"
click node_semantic "https://github.com/theasthenosphere/samia/blob/main/samia/core/semantic_recall.py"
click node_vector "https://github.com/theasthenosphere/samia/blob/main/samia/core/vector.py"
click node_hippocampus "https://github.com/theasthenosphere/samia/blob/main/samia/core/hippocampus/__init__.py"
click node_entity "https://github.com/theasthenosphere/samia/blob/main/samia/core/entity_index.py"
click node_tier "https://github.com/theasthenosphere/samia/blob/main/samia/core/tier.py"
click node_chains "https://github.com/theasthenosphere/samia/blob/main/samia/core/chain.py"
click node_hebbian "https://github.com/theasthenosphere/samia/blob/main/samia/core/bio/hebbian.py"
click node_consolidation "https://github.com/theasthenosphere/samia/blob/main/samia/core/consolidation.py"
click node_fact_extract "https://github.com/theasthenosphere/samia/blob/main/samia/core/fact_extractor.py"
click node_integrity "https://github.com/theasthenosphere/samia/blob/main/samia/core/integrity/repair.py"
click node_daemon "https://github.com/theasthenosphere/samia/blob/main/samia/runtime/maintenanced.py"
click node_rem "https://github.com/theasthenosphere/samia/blob/main/samia/runtime/rem_cycle/driver.py"
click node_contradiction "https://github.com/theasthenosphere/samia/blob/main/samia/runtime/contradiction/passes.py"
click node_inference "https://github.com/theasthenosphere/samia/blob/main/samia/runtime/inference.py"
click node_bio "https://github.com/theasthenosphere/samia/blob/main/samia/core/bio/replay.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_search,node_write,node_context_tools toneBlue
class node_chainogram,node_semantic,node_vector,node_hippocampus,node_entity toneAmber
class node_tier,node_chains,node_hebbian,node_consolidation,node_fact_extract,node_integrity toneMint
class node_daemon,node_rem,node_contradiction,node_inference,node_bio toneRose
class node_agent toneIndigo
```

## Components

### Agent interface

- [MCP server](https://github.com/theasthenosphere/samia/blob/main/samia/mcp_server_main.py): `samia/mcp_server_main.py`
- [Memory search](https://github.com/theasthenosphere/samia/blob/main/samia/core/mcp_server/search.py): `samia/core/mcp_server/search.py`
- [Memory writes](https://github.com/theasthenosphere/samia/blob/main/samia/core/mcp_server/write.py): `samia/core/mcp_server/write.py`
- [Context tools](https://github.com/theasthenosphere/samia/blob/main/samia/core/mcp_server/context_tools.py): `samia/core/mcp_server/context_tools.py`

### Recall and context

- [Chainogram retrieval](https://github.com/theasthenosphere/samia/blob/main/samia/core/context_extension/retrieval.py): `samia/core/context_extension/retrieval.py`
- [Semantic recall](https://github.com/theasthenosphere/samia/blob/main/samia/core/semantic_recall.py): `samia/core/semantic_recall.py`
- [Vector indexes](https://github.com/theasthenosphere/samia/blob/main/samia/core/vector.py): `samia/core/vector.py`
- [Hippocampal fast store](https://github.com/theasthenosphere/samia/blob/main/samia/core/hippocampus/__init__.py): `samia/core/hippocampus/__init__.py`
- [Entity bridges](https://github.com/theasthenosphere/samia/blob/main/samia/core/entity_index.py): `samia/core/entity_index.py`

### Memory lifecycle

- [Tiered memory store](https://github.com/theasthenosphere/samia/blob/main/samia/core/tier.py): `samia/core/tier.py`
- [Episodic chains](https://github.com/theasthenosphere/samia/blob/main/samia/core/chain.py): `samia/core/chain.py`
- [Hebbian web](https://github.com/theasthenosphere/samia/blob/main/samia/core/bio/hebbian.py): `samia/core/bio/hebbian.py`
- [Consolidation](https://github.com/theasthenosphere/samia/blob/main/samia/core/consolidation.py): `samia/core/consolidation.py`
- [Fact extraction](https://github.com/theasthenosphere/samia/blob/main/samia/core/fact_extractor.py): `samia/core/fact_extractor.py`
- [Integrity repair](https://github.com/theasthenosphere/samia/blob/main/samia/core/integrity/repair.py): `samia/core/integrity/repair.py`

### Autonomous upkeep

- [Maintenance daemon](https://github.com/theasthenosphere/samia/blob/main/samia/runtime/maintenanced.py): `samia/runtime/maintenanced.py`
- [REM cycle](https://github.com/theasthenosphere/samia/blob/main/samia/runtime/rem_cycle/driver.py): `samia/runtime/rem_cycle/driver.py`
- [Contradiction checks](https://github.com/theasthenosphere/samia/blob/main/samia/runtime/contradiction/passes.py): `samia/runtime/contradiction/passes.py`
- [Local inference](https://github.com/theasthenosphere/samia/blob/main/samia/runtime/inference.py): `samia/runtime/inference.py`
- [Memory replay](https://github.com/theasthenosphere/samia/blob/main/samia/core/bio/replay.py): `samia/core/bio/replay.py`

### Other components

- **AI agent**

## Connections

- AI agent → MCP server: invokes tools
- MCP server → Memory search: delegates search
- MCP server → Memory writes: delegates writes
- MCP server → Context tools: delegates context
- Memory search → Vector indexes: queries indexes
- Memory search → Hippocampal fast store: queries fast store
- Memory search → Hebbian web: reads coactivation
- Context tools → Chainogram retrieval: retrieves chains
- Context tools → Semantic recall: composes facts
- Chainogram retrieval → Episodic chains: reads chains
- Chainogram retrieval → Hebbian web: scores associations
- Chainogram retrieval → Entity bridges: queries bridges
- Memory writes → Tiered memory store: writes memories
- Consolidation → Tiered memory store: consolidates store
- Consolidation → Fact extraction: extracts facts
- Maintenance daemon → REM cycle: drives upkeep
- REM cycle → Consolidation: runs offline work
- REM cycle → Contradiction checks: sweeps candidates
- Contradiction checks → Local inference: requests judgment
- Maintenance daemon → Memory replay: runs replay
- Maintenance daemon → Integrity repair: runs repair