# rendevouz999/agent-core-memory architecture

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

- Interactive diagram: https://gitdiagram.com/rendevouz999/agent-core-memory
- Repository: https://github.com/rendevouz999/agent-core-memory

## Overview

Agent Core Memory is a standalone, file-native memory engine. Its principal workflow is to initialize a workspace-scoped service, persist canonical Markdown memories, and search them with lexical retrieval and optional semantic ranking; users can also record use and feedback, manage memory lifecycles, and transfer records. The graph includes the README’s major capabilities, while unsampled subsystem links are dashed where implementation calls could not be verified from excerpts. Paths and relationships reflect the supplied tree and source index.

Main entry points: [`src/memory/service.ts`](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/service.ts) (Memory Service), [`src/memory/store.ts`](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/store.ts) (File Memory Store), [`src/memory/retrieval.ts`](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/retrieval.ts) (Hybrid Retrieval), [`src/memory/index.ts`](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/index.ts) (Semantic Index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Service API"]
  node_standalone["Standalone Setup<br/>[standalone.ts]"]
  node_service["Memory Service<br/>[service.ts]"]
end

subgraph group_records["Records And Lifecycle"]
  node_markdown["Markdown Records<br/>[note-format.ts]"]
  node_revisions["Revision History<br/>[revisions.ts]"]
  node_relations["Links And Evolution<br/>[relations.ts]"]
  node_feedback["Feedback Lifecycle<br/>[feedback.ts]"]
  node_consolidation["Consolidation Review<br/>[consolidation.ts]"]
  node_retirement["Retirement Review<br/>[retirement.ts]"]
  node_transfer["Import Export<br/>[transfer.ts]"]
end

subgraph group_search["Retrieval And Indexing"]
  node_retrieval["Hybrid Retrieval<br/>[retrieval.ts]"]
  node_bm25["BM25 Ranking<br/>[bm25.ts]"]
  node_index[("Semantic Index<br/>[index.ts]")]
  node_embedder["Cloud Embeddings<br/>[embedder.ts]"]
  node_repair["Embedding Repair"]
end

subgraph group_evidence["Evidence And Learning"]
  node_provenance["Source Provenance<br/>[provenance.ts]"]
  node_workflow["Workflow Verification"]
  node_ledger[("Retrieval Use Ledger")]
  node_tracker[("Activity Tracking")]
end

subgraph group_storage["Persistence"]
  node_store[("File Memory Store<br/>[store.ts]")]
  node_atomic["Atomic File Writes<br/>[atomic-file.ts]"]
  node_locking["Process Locking<br/>[lock.ts]"]
  node_paths["Memory Paths<br/>[paths.ts]"]
end

node_caller(("Memory User"))
node_cloudflare["Workers AI"]

node_caller -->|"initializes"| node_standalone
node_standalone -->|"creates service"| node_service
node_caller -->|"uses memory"| node_service
node_service -->|"initializes store"| node_store
node_store -.->|"parses records"| node_markdown
node_store -.->|"tracks revisions"| node_revisions
node_service -->|"searches records"| node_retrieval
node_retrieval -->|"ranks lexically"| node_bm25
node_retrieval -.->|"uses semantic context"| node_index
node_index -.->|"embeds documents"| node_embedder
node_index -.->|"repairs embeddings"| node_repair
node_service -->|"captures provenance"| node_provenance
node_service -->|"validates use"| node_workflow
node_service -.->|"records use"| node_ledger
node_ledger -.->|"correlates activity"| node_tracker
node_service -.->|"manages feedback"| node_feedback
node_service -.->|"manages links"| node_relations
node_service -.->|"offers review"| node_consolidation
node_service -.->|"offers review"| node_retirement
node_service -.->|"transfers records"| node_transfer
node_store -.->|"writes atomically"| node_atomic
node_store -.->|"locks access"| node_locking
node_service -->|"resolves storage"| node_paths
node_embedder -->|"requests embeddings"| node_cloudflare

click node_standalone "https://github.com/rendevouz999/agent-core-memory/blob/main/src/standalone.ts"
click node_service "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/service.ts"
click node_store "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/store.ts"
click node_markdown "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/note-format.ts"
click node_revisions "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/revisions.ts"
click node_relations "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/relations.ts"
click node_feedback "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/feedback.ts"
click node_consolidation "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/consolidation.ts"
click node_retirement "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/retirement.ts"
click node_transfer "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/transfer.ts"
click node_retrieval "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/retrieval.ts"
click node_bm25 "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/bm25.ts"
click node_index "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/index.ts"
click node_embedder "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/embedder.ts"
click node_repair "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/embedding-repair.ts"
click node_provenance "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/provenance.ts"
click node_workflow "https://github.com/rendevouz999/agent-core-memory/blob/main/src/learning/workflow-evidence.ts"
click node_ledger "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/retrieval-ledger.ts"
click node_tracker "https://github.com/rendevouz999/agent-core-memory/blob/main/src/tracker/activity-tracker.ts"
click node_atomic "https://github.com/rendevouz999/agent-core-memory/blob/main/src/persistence/atomic-file.ts"
click node_locking "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/lock.ts"
click node_paths "https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/paths.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_standalone,node_service,node_caller toneBlue
class node_markdown,node_revisions,node_relations,node_feedback,node_consolidation,node_retirement,node_transfer toneAmber
class node_retrieval,node_bm25,node_index,node_embedder,node_repair toneMint
class node_provenance,node_workflow,node_ledger,node_tracker,node_cloudflare toneRose
class node_store,node_atomic,node_locking,node_paths toneIndigo
```

## Components

### Service API

- [Standalone Setup](https://github.com/rendevouz999/agent-core-memory/blob/main/src/standalone.ts): `src/standalone.ts`
- [Memory Service](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/service.ts): `src/memory/service.ts`

### Records And Lifecycle

- [Markdown Records](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/note-format.ts): `src/memory/note-format.ts`
- [Revision History](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/revisions.ts): `src/memory/revisions.ts`
- [Links And Evolution](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/relations.ts): `src/memory/relations.ts`
- [Feedback Lifecycle](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/feedback.ts): `src/memory/feedback.ts`
- [Consolidation Review](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/consolidation.ts): `src/memory/consolidation.ts`
- [Retirement Review](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/retirement.ts): `src/memory/retirement.ts`
- [Import Export](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/transfer.ts): `src/memory/transfer.ts`

### Retrieval And Indexing

- [Hybrid Retrieval](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/retrieval.ts): `src/memory/retrieval.ts`
- [BM25 Ranking](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/bm25.ts): `src/memory/bm25.ts`
- [Semantic Index](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/index.ts): `src/memory/index.ts`
- [Cloud Embeddings](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/embedder.ts): `src/memory/embedder.ts`
- [Embedding Repair](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/embedding-repair.ts): `src/memory/embedding-repair.ts`

### Evidence And Learning

- [Source Provenance](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/provenance.ts): `src/memory/provenance.ts`
- [Workflow Verification](https://github.com/rendevouz999/agent-core-memory/blob/main/src/learning/workflow-evidence.ts): `src/learning/workflow-evidence.ts`
- [Retrieval Use Ledger](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/retrieval-ledger.ts): `src/memory/retrieval-ledger.ts`
- [Activity Tracking](https://github.com/rendevouz999/agent-core-memory/blob/main/src/tracker/activity-tracker.ts): `src/tracker/activity-tracker.ts`

### Persistence

- [File Memory Store](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/store.ts): `src/memory/store.ts`
- [Atomic File Writes](https://github.com/rendevouz999/agent-core-memory/blob/main/src/persistence/atomic-file.ts): `src/persistence/atomic-file.ts`
- [Process Locking](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/lock.ts): `src/memory/lock.ts`
- [Memory Paths](https://github.com/rendevouz999/agent-core-memory/blob/main/src/memory/paths.ts): `src/memory/paths.ts`

### Other components

- **Memory User**
- **Workers AI**

## Connections

- Memory User → Standalone Setup: initializes (evidence: `README.md`)
- Standalone Setup → Memory Service: creates service (evidence: `src/standalone.ts`)
- Memory User → Memory Service: uses memory (evidence: `README.md`)
- Memory Service → File Memory Store: initializes store (evidence: `src/memory/service.ts`)
- File Memory Store → Markdown Records: parses records (evidence: `src/memory/store.ts`)
- File Memory Store → Revision History: tracks revisions (evidence: `src/memory/store.ts`)
- Memory Service → Hybrid Retrieval: searches records (evidence: `src/memory/service.ts`)
- Hybrid Retrieval → BM25 Ranking: ranks lexically (evidence: `src/memory/retrieval.ts`)
- Hybrid Retrieval → Semantic Index: uses semantic context (evidence: `src/memory/retrieval.ts`)
- Semantic Index → Cloud Embeddings: embeds documents (evidence: `src/memory/index.ts`)
- Semantic Index → Embedding Repair: repairs embeddings (evidence: `src/memory/index.ts`)
- Memory Service → Source Provenance: captures provenance (evidence: `src/memory/service.ts`)
- Memory Service → Workflow Verification: validates use (evidence: `src/memory/service.ts`)
- Memory Service → Retrieval Use Ledger: records use (evidence: `src/memory/service.ts`)
- Retrieval Use Ledger → Activity Tracking: correlates activity (evidence: `src/memory/retrieval-ledger.ts`)
- Memory Service → Feedback Lifecycle: manages feedback (evidence: `src/memory/service.ts`)
- Memory Service → Links And Evolution: manages links (evidence: `src/memory/service.ts`)
- Memory Service → Consolidation Review: offers review (evidence: `src/memory/service.ts`)
- Memory Service → Retirement Review: offers review (evidence: `src/memory/service.ts`)
- Memory Service → Import Export: transfers records (evidence: `src/memory/service.ts`)
- File Memory Store → Atomic File Writes: writes atomically
- File Memory Store → Process Locking: locks access (evidence: `src/memory/store.ts`)
- Memory Service → Memory Paths: resolves storage (evidence: `src/memory/service.ts`)
- Cloud Embeddings → Workers AI: requests embeddings (evidence: `src/memory/embedder.ts`)
