# jayzeng/agentmemory architecture

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

- Interactive diagram: https://gitdiagram.com/jayzeng/agentmemory
- Repository: https://github.com/jayzeng/agentmemory

## Overview

AgentMemory is a local-first memory layer for coding agents: users or agent clients submit memory commands, which read, write, organize, and retrieve Markdown memory, then return context or search results. CLI and MCP are distinct entry points into shared core behavior; agent hooks support installation and capture checks for several environments. The README also documents optional qmd search and skills installation. Core storage and qmd behavior are supported by the excerpts, but details of individual write/read operations and some CLI dispatch are unsampled, so uncertain internal links are omitted.

Main entry points: [`src/core.ts`](https://github.com/jayzeng/agentmemory/blob/main/src/core.ts) (Memory core), [`src/cli.ts`](https://github.com/jayzeng/agentmemory/blob/main/src/cli.ts) (CLI), [`src/mcp-server.ts`](https://github.com/jayzeng/agentmemory/blob/main/src/mcp-server.ts) (MCP server), [`src/hooks.ts`](https://github.com/jayzeng/agentmemory/blob/main/src/hooks.ts) (Hook installer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[cli.ts]"]
  node_mcp["MCP server<br/>[mcp-server.ts]"]
end

subgraph group_memory["Memory operations"]
  node_core["Memory core<br/>[core.ts]"]
  node_markdown[("Markdown memory")]
  node_redaction["Secret redaction<br/>[core.ts]"]
  node_scratchpad["Scratchpad<br/>[core.ts]"]
end

subgraph group_integrations["Agent integrations"]
  node_skills["Skills install<br/>[cli.ts]"]
  node_hooks["Hook installer<br/>[hooks.ts]"]
  node_agentconfigs[("Agent configs")]
  node_capture["Capture checks<br/>[capture-check.ts]"]
  node_codexcheck["Codex transcript check"]
  node_cursorcapture["Cursor capture<br/>[cursor-capture.ts]"]
end

subgraph group_retrieval["Retrieval"]
  node_context["Context builder<br/>[core.ts]"]
  node_qmd["qmd search"]
end

node_user(("Developer / agent"))
node_agents(("Coding agents"))

node_user -->|"runs commands"| node_cli
node_user -->|"sends tool calls"| node_mcp
node_cli -->|"calls operations"| node_core
node_mcp -->|"calls operations"| node_core
node_core -->|"reads and writes"| node_markdown
node_core -->|"redacts content"| node_redaction
node_core -->|"manages items"| node_scratchpad
node_core -.->|"invokes search"| node_qmd
node_cli -->|"builds context"| node_context
node_mcp -->|"builds context"| node_context
node_cli -->|"installs skills"| node_skills
node_cli -->|"installs hooks"| node_hooks
node_hooks -->|"updates configs"| node_agentconfigs
node_agents -->|"provides transcripts"| node_capture
node_capture -->|"checks Codex"| node_codexcheck
node_agents -->|"provides events"| node_cursorcapture
node_cursorcapture -->|"uses memory directory"| node_core
node_agents -->|"uses CLI"| node_cli
node_agents -->|"calls tools"| node_mcp
node_qmd -.->|"indexes files"| node_markdown

click node_cli "https://github.com/jayzeng/agentmemory/blob/main/src/cli.ts"
click node_mcp "https://github.com/jayzeng/agentmemory/blob/main/src/mcp-server.ts"
click node_core "https://github.com/jayzeng/agentmemory/blob/main/src/core.ts"
click node_redaction "https://github.com/jayzeng/agentmemory/blob/main/src/core.ts"
click node_scratchpad "https://github.com/jayzeng/agentmemory/blob/main/src/core.ts"
click node_context "https://github.com/jayzeng/agentmemory/blob/main/src/core.ts"
click node_skills "https://github.com/jayzeng/agentmemory/blob/main/src/cli.ts"
click node_hooks "https://github.com/jayzeng/agentmemory/blob/main/src/hooks.ts"
click node_capture "https://github.com/jayzeng/agentmemory/blob/main/src/capture-check.ts"
click node_codexcheck "https://github.com/jayzeng/agentmemory/blob/main/src/codex-capture-check.ts"
click node_cursorcapture "https://github.com/jayzeng/agentmemory/blob/main/src/cursor-capture.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_cli,node_mcp toneBlue
class node_core,node_markdown,node_redaction,node_scratchpad toneAmber
class node_skills,node_hooks,node_agentconfigs,node_capture,node_codexcheck,node_cursorcapture toneMint
class node_context,node_qmd toneRose
class node_user,node_agents toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/jayzeng/agentmemory/blob/main/src/cli.ts): `src/cli.ts`
- [MCP server](https://github.com/jayzeng/agentmemory/blob/main/src/mcp-server.ts): `src/mcp-server.ts`

### Memory operations

- [Memory core](https://github.com/jayzeng/agentmemory/blob/main/src/core.ts): `src/core.ts`
- **Markdown memory**
- [Secret redaction](https://github.com/jayzeng/agentmemory/blob/main/src/core.ts): `src/core.ts`
- [Scratchpad](https://github.com/jayzeng/agentmemory/blob/main/src/core.ts): `src/core.ts`

### Agent integrations

- [Skills install](https://github.com/jayzeng/agentmemory/blob/main/src/cli.ts): `src/cli.ts`
- [Hook installer](https://github.com/jayzeng/agentmemory/blob/main/src/hooks.ts): `src/hooks.ts`
- **Agent configs**
- [Capture checks](https://github.com/jayzeng/agentmemory/blob/main/src/capture-check.ts): `src/capture-check.ts`
- [Codex transcript check](https://github.com/jayzeng/agentmemory/blob/main/src/codex-capture-check.ts): `src/codex-capture-check.ts`
- [Cursor capture](https://github.com/jayzeng/agentmemory/blob/main/src/cursor-capture.ts): `src/cursor-capture.ts`

### Retrieval

- [Context builder](https://github.com/jayzeng/agentmemory/blob/main/src/core.ts): `src/core.ts`
- **qmd search**

### Other components

- **Developer / agent**
- **Coding agents**

## Connections

- Developer / agent → CLI: runs commands
- Developer / agent → MCP server: sends tool calls
- CLI → Memory core: calls operations
- MCP server → Memory core: calls operations
- Memory core → Markdown memory: reads and writes
- Memory core → Secret redaction: redacts content
- Memory core → Scratchpad: manages items
- Memory core → qmd search: invokes search
- CLI → Context builder: builds context
- MCP server → Context builder: builds context
- CLI → Skills install: installs skills
- CLI → Hook installer: installs hooks
- Hook installer → Agent configs: updates configs
- Coding agents → Capture checks: provides transcripts
- Capture checks → Codex transcript check: checks Codex
- Coding agents → Cursor capture: provides events
- Cursor capture → Memory core: uses memory directory
- Coding agents → CLI: uses CLI
- Coding agents → MCP server: calls tools
- qmd search → Markdown memory: indexes files