AgentMemory 🛡️

🌐 中文版 | English

---

AgentMemory is a compilation-free, lightweight, and universal persistent memory system (Universal Agent Memory - UAM). It allows multiple developer agents (such as Claude Code, OpenCode, ChatGPT desktop (Codex runtime), Antigravity CLI, and Grok) to share, record, and query context observations and decisions across different workspaces.

🌟 Features

• Cross-Agent Memory Sharing: Shares historical session facts, architectural decisions, and bug-fixing notes across different development assistants.
• Native SQLite & Lightweight Embeddings: Uses better-sqlite3 with WAL, bounded lock retries, and atomic writes, alongside a pure JavaScript Feature Hashing Vectorizer. Supported Windows x64/ARM64 installs use bundled native binaries; other platforms may require build tools.
• Hybrid Search: Combines SQLite FTS5 BM25 keyword matching with Cosine Similarity vector retrieval for highly relevant results.
• Background Summarization: Uses the DeepSeek Flash API to summarize session tool logs asynchronously in the background.
• Daily Memory Digests: Runs a daily per-project synthesis job that filters low-signal observations, writes compact fact/decision/action digests, and feeds recent digests into startup context.
• Secure Global Config: Stores API keys and settings globally (~/.agentmem/.env) to keep codebase repositories clean and credentials safe.
• Loopback Admin Console: Exposes a local-only /admin page for inspecting the database, filtering observations, and toggling global memory read/write gates at runtime.
• Persistent Runtime Policy: Persists readEnabled and writeEnabled flags in SQLite so runtime gating survives worker restarts.

---

🏗️ Architecture

graph TD
    subgraph Clients [Developer Assistants]
        CC[Claude Code]
        OC[OpenCode]
        CX["ChatGPT desktop<br/>(Codex runtime)"]
        AG[Antigravity CLI]
        GK[Grok]
    end

    subgraph AgentMemory Core [AgentMemory System]
        CLI[Global CLI Wrapper]
        Worker[Background HTTP Worker Port 38888]
        MCP[Stdio MCP Server]
        DB[(WASM SQLite + FTS5)]
    end

    CC -- Stdio MCP / Hooks --> MCP
    OC -- Stdio MCP / ESM Plugin --> MCP
    CX -- Stdio MCP --> MCP
    AG -- Stdio MCP --> MCP
    GK -- Stdio MCP / Hooks --> MCP

    CC -- Post-Tool Event --> Worker
    OC -- Post-Tool Event --> Worker
    GK -- Lifecycle Events --> Worker

    Worker -- Async Summarization --> LLM[DeepSeek Flash API]
    Worker -- Write Obs --> DB
    MCP -- Query / Write --> DB

---

🚀 Getting Started

1. Prerequisites

• Node.js (v22+; Node 24 recommended)
• Upgrading an existing WASM-backed installation: follow Native SQLite Migration to stop older Worker/MCP processes and back up the database before switching.

2. Installation

Clone the repository and build the distribution files:

git clone https://github.com/KuanChen01/AgentMemory.git
cd AgentMemory
npm install
npm run build

The project .npmrc disables dependency install scripts so SQLite uses its bundled native binary. Current dependencies require no install scripts; npm run build still runs explicitly. Platforms without a bundled binary require a separate native build with suitable tools.

Link the executable globally to register the agentmem CLI:

npm link --ignore-scripts

3. Configuration

Set up your global configuration file in your user home directory:

File Path: ~/.agentmem/.env (Create parent directory .agentmem if it doesn't exist)

# General LLM credentials (supports OpenAI, DeepSeek, Mimo, Ark, local Ollama, etc.)
AGENTMEM_LLM_API_KEY=your_api_key_here
AGENTMEM_LLM_API_URL=https://api.deepseek.com/v1
AGENTMEM_LLM_MODEL=deepseek-chat

# Optional: Set to true if your proxy platform doesn't support JSON Mode parameters
AGENTMEM_LLM_DISABLE_JSON_MODE=false

# Optional: Custom JSON headers required by your proxy pools or gateway (e.g. Volcengine Ark)
# AGENTMEM_LLM_HEADERS={"X-Custom-Auth":"value"}

# Local service port
AGENTMEM_PORT=38888

4. Automatic Agent Registration

Run the installer to automatically configure settings for Claude Code, OpenCode, ChatGPT desktop (Codex runtime), Antigravity, and Grok:

agentmem install

If you want the command to fail whenever any one of the five agents cannot be configured, use:

agentmem install --strict

The installer is now backup-first and merge-first:

• It stores install state in ~/.agentmem/install-state.json
• It keeps pristine baselines under ~/.agentmem/backups/ when available
• It merges only AgentMemory-owned hooks / MCP entries instead of replacing whole hook arrays

To remove AgentMemory from the current machine without deleting the repo checkout, use:

agentmem uninstall --strict

Add --purge-all if you also want to remove the retained install-state and backup artifacts after cleanup.

For a second Windows machine, use the dedicated bootstrap entry instead of repeating the setup manually:

.\bootstrap-second-machine.cmd

Detailed Chinese walkthrough: docs/Second Machine Bootstrap Guide.zh.md

---

💻 Command Reference

Run these commands globally from any directory:

• Start Worker Manually: agentmem start (optional foreground control; lifecycle hooks safely auto-start the background worker when it is unavailable)
• Stop Worker: agentmem stop (sends a graceful shutdown trigger to the local worker)
• Check Status: agentmem status (verifies if the port 38888 is active)
• Print Version: agentmem version
• Run Setup: agentmem install (updates Claude Code, OpenCode, Codex, Antigravity, and Grok settings)
• Strict Setup: agentmem install --strict (fails if any one of the five agents cannot be configured)
• Uninstall Local Integration: agentmem uninstall --strict (removes AgentMemory-managed hooks, MCP entries, plugin artifacts, .env, and database files from the current machine)
• Purge Local Install State: agentmem uninstall --strict --purge-all (also removes retained backup and install-state artifacts)
• Second-Machine Bootstrap: agentmem bootstrap-win --strict or bootstrap-second-machine.cmd
• Release Manifest: agentmem release-manifest --json (prints the machine-readable release policy and current version)
• Release Plan: npm run release:plan -- --next patch|minor|major (prints the manual release checklist for the next version)
• Release Bump: npm run release:bump -- --next patch|minor|major (updates the root package version metadata before a release commit)

🪟 Windows Bootstrap

For a same-shape second Windows machine, the recommended path is:

git clone https://github.com/KuanChen01/AgentMemory.git
cd AgentMemory
.\bootstrap-second-machine.cmd

The bootstrap script runs npm install --ignore-scripts, npm run build, creates or validates %USERPROFILE%\.agentmem\.env, runs npm link --ignore-scripts, configures all five agents, probes or starts the worker, and opens /admin.

If %USERPROFILE%\.agentmem\.env is missing, bootstrap writes a blank scaffold and stops with an actionable error. Fill the AGENTMEM_LLM_* values, then rerun the command.

📦 Release Discipline

AgentMemory now treats product releases as a first-class maintainer workflow:

• Official releases are published from master only.
• Versioning is strict SemVer with tags shaped like v1.2.3.
• The current v1 distribution channel is GitHub Release + default source archives.
• Release metadata is exposed through the CLI (agentmem release-manifest) and /admin/api/overview, and /admin/api/release-check now compares the current checkout against the latest published GitHub Release.

Detailed maintainer workflow: docs/Release Process.md

Use branches and reviewed PRs before merging, releasing, and upgrading each machine independently. Keep local configuration and memories on their own machine. See Reviewed Updates. Existing Worker/MCP processes must restart to load new code; updating source or running bootstrap does not update an already-running process.

Memory processing on the official DeepSeek endpoint uses non-thinking mode and records per-machine usage. Custom summary output budgets are optional and off by default, with separate tool-summary and daily-digest controls in LLM Settings. See LLM Cost Controls.

---

🧭 Admin Console

After the worker is running, open:

http://127.0.0.1:38888/admin

The admin console is intentionally restricted to loopback clients. It is not exposed to non-local network addresses.

Windows local control now has two entrypoints:

• npm run workbench
• start-workbench.cmd

npm run workbench keeps the direct one-click flow: build the repo, probe http://127.0.0.1:38888/admin/api/overview, reuse or start the worker, and open /admin.

start-workbench.cmd is now the interactive control entrypoint. With no arguments it probes the current status first, then shows a one-shot menu for Start, Stop, Restart, Status, Open Admin, and Exit. With arguments it supports:

• start-workbench.cmd start|stop|restart|status|open-admin|menu
• start-workbench.cmd start --no-open
• start-workbench.cmd restart --port 38889 --no-open

The page provides:

• Runtime for global readEnabled / writeEnabled control, project inventory, daily digest status / manual run / scheduler settings, workbench posture, and a read-only GitHub Release update check with manual upgrade guidance
• Procedural Skills for reviewing digest skill_candidates, promoting them to draft, flipping lifecycle status, recording success/failure/rejected/skipped feedback, inspecting feedback history, evidence, lifecycle, recommendation signals, and the latest automatic post-task review artifacts next to task-level query validation
• LLM Settings for switching AGENTMEM_LLM_MODEL, updating the OpenAI-compatible API base URL, preserving or replacing the API key, and running a live connection test
• Project Context for the current ProjectContextView, recent daily digests, rendered startup text, bounded context package metrics, temporal slice diagnostics, and policy decision trace
• State Lab for explicit structured state reads and writes
• Search Diagnostics for raw hybrid search scores (hybrid_score, fts_score, vector_score) and low-signal title visibility
• Observation Ledger for filterable observation browsing and detailed drill-down

Structured state and context view

AgentMemory now separates memory into explicit layers:

• Observations remain the append-only historical ledger used for hybrid search and detailed recall.
• State facts store explicit current or historical truth with effective_at, recorded_at, and superseded_at.
• Daily digests store scheduled or manually triggered per-project summaries with fact, decision, command, open-question, and next-action lists. Digest output is not auto-promoted into state facts.
• Procedural skills are now first-class, reviewable memory objects with draft/enabled/disabled/retired states plus success/failure feedback logs.

The policy brain is now explicit instead of being scattered across hooks and ad-hoc call sites:

• memory-policy.ts centralizes read decisions, suppresses routine read/status/search/view/run tool noise only when it has neither modified-file evidence nor a substantive outcome, and owns draft promotion gates for procedural skill candidates. Explicit record_memory milestones, failures, verifie