# v1b3x0r/living-memory-engine architecture

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

- Interactive diagram: https://gitdiagram.com/v1b3x0r/living-memory-engine
- Repository: https://github.com/v1b3x0r/living-memory-engine

## Overview

LME’s main workflow is an agent adding or recalling shared memory through an MCP tool: the server delegates to the memory engine, which retrieves, updates, and composes bounded context using storage and model-provider ports. The repository also contains the browser lab, which exercises the engine through chat, ambient observation, and a memory-inspection pane, plus a frozen mobile prototype. Core memory behavior is sourced from engine excerpts; hosted-world capabilities such as OAuth, handoffs, and client keys are documented but their server implementation is outside this repository.

Main entry points: [`engine/src/engine.ts`](https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/engine.ts) (Memory engine), [`web/src/lib/engine.ts`](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/engine.ts) (Browser engine setup), [`web/src/ui/chat.ts`](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/ui/chat.ts) (Chat interface), [`web/src/ui/debug.ts`](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/ui/debug.ts) (Memory inspector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Memory engine"]
  node_memory["Memory engine<br/>[engine.ts]"]
  node_consolidation["Memory lifecycle<br/>[consolidation.ts]"]
  node_retrieval["Semantic retrieval<br/>[vector.ts]"]
  node_attribution["Memory attribution<br/>[attribution.ts]"]
  node_injection["Context injection<br/>[inject.ts]"]
  node_ports["Engine ports<br/>[ports.ts]"]
  node_adapters["Provider adapters<br/>[adapters.ts]"]
end

subgraph group_mcp["MCP server"]
  node_mcpserver["Tool server<br/>[server.ts]"]
  node_brain["Memory tools<br/>[brain.ts]"]
  node_filedata[("JSON snapshot<br/>[storage.ts]")]
end

subgraph group_web["Browser lab"]
  node_entry["App bootstrap<br/>[main.ts]"]
  node_chatui["Chat interface<br/>[chat.ts]"]
  node_memoryui["Memory inspector<br/>[debug.ts]"]
  node_browserengine["Browser engine setup<br/>[engine.ts]"]
  node_browserstore[("IndexedDB snapshots<br/>[storage.ts]")]
  node_ambient["Ambient observer<br/>[ambient.ts]"]
  node_respond["Lab response<br/>[labrespond.ts]"]
  node_world["World state<br/>[world.ts]"]
  node_personas["Personas<br/>[personas.ts]"]
  node_profiles["Model profiles<br/>[config.ts]"]
end

subgraph group_mobile["Mobile prototype"]
  node_mobileapp["Mobile screens<br/>[index.tsx]"]
  node_mobileengine["Mobile engine setup<br/>[engine.ts]"]
  node_sqlstore[("SQLite snapshots<br/>[storage.ts]")]
end

node_agent(("MCP agent"))
node_openai["OpenAI-compatible API"]
node_browseruser(("Browser user"))
node_mobileuser(("Mobile user"))

node_agent -->|"calls tools"| node_mcpserver
node_mcpserver -->|"dispatches tools"| node_brain
node_brain -->|"uses engine"| node_memory
node_brain -->|"loads and saves"| node_filedata
node_memory -->|"decays and merges"| node_consolidation
node_memory -->|"searches memories"| node_retrieval
node_memory -->|"places memories"| node_attribution
node_memory -->|"formats context"| node_injection
node_memory -->|"uses interfaces"| node_ports
node_adapters -->|"implements ports"| node_ports
node_adapters -.->|"calls API"| node_openai
node_browseruser -->|"uses lab"| node_entry
node_entry -->|"mounts chat"| node_chatui
node_entry -->|"mounts inspector"| node_memoryui
node_chatui -->|"gets engine"| node_browserengine
node_chatui -->|"requests replies"| node_respond
node_chatui -->|"selects persona"| node_personas
node_browserengine -->|"creates storage"| node_browserstore
node_browserengine -->|"configures providers"| node_profiles
node_ambient -->|"updates world"| node_world
node_ambient -->|"observes via engine"| node_browserengine
node_memoryui -->|"inspects engine"| node_browserengine
node_memoryui -->|"wipes world"| node_ambient
node_memoryui -->|"selects persona"| node_personas
node_mobileuser -.->|"uses prototype"| node_mobileapp
node_mobileapp -.->|"uses engine"| node_mobileengine
node_mobileengine -->|"creates storage"| node_sqlstore

click node_mcpserver "https://github.com/v1b3x0r/living-memory-engine/blob/main/lme-mcp/src/server.ts"
click node_brain "https://github.com/v1b3x0r/living-memory-engine/blob/main/lme-mcp/src/brain.ts"
click node_filedata "https://github.com/v1b3x0r/living-memory-engine/blob/main/lme-mcp/src/storage.ts"
click node_memory "https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/engine.ts"
click node_consolidation "https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/consolidation.ts"
click node_retrieval "https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/vector.ts"
click node_attribution "https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/attribution.ts"
click node_injection "https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/inject.ts"
click node_ports "https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/ports.ts"
click node_adapters "https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/provider/adapters.ts"
click node_entry "https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/main.ts"
click node_chatui "https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/ui/chat.ts"
click node_memoryui "https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/ui/debug.ts"
click node_browserengine "https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/engine.ts"
click node_browserstore "https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/storage.ts"
click node_ambient "https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/ambient.ts"
click node_respond "https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/labrespond.ts"
click node_world "https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/world.ts"
click node_personas "https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/personas.ts"
click node_profiles "https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/config.ts"
click node_mobileapp "https://github.com/v1b3x0r/living-memory-engine/blob/main/mobile/app/index.tsx"
click node_mobileengine "https://github.com/v1b3x0r/living-memory-engine/blob/main/mobile/lib/engine.ts"
click node_sqlstore "https://github.com/v1b3x0r/living-memory-engine/blob/main/mobile/lib/storage.ts"

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_memory,node_consolidation,node_retrieval,node_attribution,node_injection,node_ports,node_adapters,node_browseruser,node_mobileuser toneBlue
class node_mcpserver,node_brain,node_filedata toneAmber
class node_entry,node_chatui,node_memoryui,node_browserengine,node_browserstore,node_ambient,node_respond,node_world,node_personas,node_profiles,node_openai toneMint
class node_mobileapp,node_mobileengine,node_sqlstore toneRose
class node_agent toneIndigo
```

## Components

### Memory engine

- [Memory engine](https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/engine.ts): `engine/src/engine.ts`
- [Memory lifecycle](https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/consolidation.ts): `engine/src/consolidation.ts`
- [Semantic retrieval](https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/vector.ts): `engine/src/vector.ts`
- [Memory attribution](https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/attribution.ts): `engine/src/attribution.ts`
- [Context injection](https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/inject.ts): `engine/src/inject.ts`
- [Engine ports](https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/src/ports.ts): `engine/src/ports.ts`
- [Provider adapters](https://github.com/v1b3x0r/living-memory-engine/blob/main/engine/provider/adapters.ts): `engine/provider/adapters.ts`

### MCP server

- [Tool server](https://github.com/v1b3x0r/living-memory-engine/blob/main/lme-mcp/src/server.ts): `lme-mcp/src/server.ts`
- [Memory tools](https://github.com/v1b3x0r/living-memory-engine/blob/main/lme-mcp/src/brain.ts): `lme-mcp/src/brain.ts`
- [JSON snapshot](https://github.com/v1b3x0r/living-memory-engine/blob/main/lme-mcp/src/storage.ts): `lme-mcp/src/storage.ts`

### Browser lab

- [App bootstrap](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/main.ts): `web/src/main.ts`
- [Chat interface](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/ui/chat.ts): `web/src/ui/chat.ts`
- [Memory inspector](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/ui/debug.ts): `web/src/ui/debug.ts`
- [Browser engine setup](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/engine.ts): `web/src/lib/engine.ts`
- [IndexedDB snapshots](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/storage.ts): `web/src/lib/storage.ts`
- [Ambient observer](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/ambient.ts): `web/src/lib/ambient.ts`
- [Lab response](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/labrespond.ts): `web/src/lib/labrespond.ts`
- [World state](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/world.ts): `web/src/lib/world.ts`
- [Personas](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/personas.ts): `web/src/lib/personas.ts`
- [Model profiles](https://github.com/v1b3x0r/living-memory-engine/blob/main/web/src/lib/config.ts): `web/src/lib/config.ts`

### Mobile prototype

- [Mobile screens](https://github.com/v1b3x0r/living-memory-engine/blob/main/mobile/app/index.tsx): `mobile/app/index.tsx`
- [Mobile engine setup](https://github.com/v1b3x0r/living-memory-engine/blob/main/mobile/lib/engine.ts): `mobile/lib/engine.ts`
- [SQLite snapshots](https://github.com/v1b3x0r/living-memory-engine/blob/main/mobile/lib/storage.ts): `mobile/lib/storage.ts`

### Other components

- **MCP agent**
- **OpenAI-compatible API**
- **Browser user**
- **Mobile user**

## Connections

- MCP agent → Tool server: calls tools (evidence: `README.md`)
- Tool server → Memory tools: dispatches tools (evidence: `lme-mcp/src/server.ts`)
- Memory tools → Memory engine: uses engine (evidence: `lme-mcp/src/brain.ts`)
- Memory tools → JSON snapshot: loads and saves (evidence: `lme-mcp/src/brain.ts`)
- Memory engine → Memory lifecycle: decays and merges (evidence: `engine/src/engine.ts`)
- Memory engine → Semantic retrieval: searches memories (evidence: `engine/src/engine.ts`)
- Memory engine → Memory attribution: places memories (evidence: `engine/src/engine.ts`)
- Memory engine → Context injection: formats context (evidence: `engine/src/engine.ts`)
- Memory engine → Engine ports: uses interfaces (evidence: `engine/src/engine.ts`)
- Provider adapters → Engine ports: implements ports (evidence: `engine/provider/adapters.ts`)
- Provider adapters → OpenAI-compatible API: calls API
- Browser user → App bootstrap: uses lab (evidence: `README.md`)
- App bootstrap → Chat interface: mounts chat (evidence: `web/src/main.ts`)
- App bootstrap → Memory inspector: mounts inspector (evidence: `web/src/main.ts`)
- Chat interface → Browser engine setup: gets engine (evidence: `web/src/ui/chat.ts`)
- Chat interface → Lab response: requests replies (evidence: `web/src/ui/chat.ts`)
- Chat interface → Personas: selects persona (evidence: `web/src/ui/chat.ts`)
- Browser engine setup → IndexedDB snapshots: creates storage (evidence: `web/src/lib/engine.ts`)
- Browser engine setup → Model profiles: configures providers (evidence: `web/src/lib/engine.ts`)
- Ambient observer → World state: updates world (evidence: `web/src/lib/ambient.ts`)
- Ambient observer → Browser engine setup: observes via engine (evidence: `web/src/lib/ambient.ts`)
- Memory inspector → Browser engine setup: inspects engine (evidence: `web/src/ui/debug.ts`)
- Memory inspector → Ambient observer: wipes world (evidence: `web/src/ui/debug.ts`)
- Memory inspector → Personas: selects persona (evidence: `web/src/ui/debug.ts`)
- Mobile user → Mobile screens: uses prototype (evidence: `README.md`)
- Mobile screens → Mobile engine setup: uses engine
- Mobile engine setup → SQLite snapshots: creates storage (evidence: `mobile/lib/engine.ts`)
