README.md

May 19, 2026 ยท View on GitHub

RAVBYTE Technologies

Agent Memory System

Persistent repository memory, worklogs, handoffs, and code graph context for AI coding agents.

npm version npm downloads CI GitHub stars License

Agent Memory System is a TypeScript CLI that creates a repository-local memory layer for AI coding agents. It generates reviewable Markdown and JSON artifacts that describe project structure, development workflow, API/storage/security context, static code graph, agent worklogs, and handoffs.

The goal is to help coding agents resume work across sessions and tools without rediscovering the codebase from scratch.

AMS is not a chatbot memory service, vector database, or agent runtime. It is a repo-local context layer for tools such as Codex, Claude Code, Cursor, Gemini CLI, Antigravity, and other coding agents that can read files before acting.

Current Benchmark Snapshot

Maintainer-run self-benchmark on 21 repository tasks. These results are checked into the repo and should be treated as early measurements, not independent validation.

MetricBaselineAMSObserved change
Average files traversed351945% fewer files
Concept accuracy66%100%+34 percentage points
Average hallucinated files1.01.00% change
Average tokens per task34,48742,467AMS used more tokens in this run

Read the benchmark summary or inspect the raw run data in benchmarks/runs/ and benchmarks/metrics/.

Why This Exists

AI coding agents often start cold. Even when a previous agent already explored the codebase, the next session may repeat the same file traversal, miss prior decisions, or change shared interfaces without checking downstream usage.

AMS makes that context explicit:

  • project structure and likely entry points
  • build, test, and quality commands
  • API, storage, security, and config notes
  • static dependency graph and blast-radius reports
  • checkpoints during long work
  • handoff notes before switching agents or sessions

Quick Start

Run once in a repository:

npx @ravbyte/agent-memory-system@latest init

This creates a memory/ directory and an AGENTS.md instruction file.

Refresh memory after structural changes:

npx @ravbyte/agent-memory-system@latest maintain --since main

If installed globally:

npm install -g @ravbyte/agent-memory-system@latest
agent-memory init
agent-memory maintain --since main

How It Fits Together

flowchart LR
  Repo[Repository] --> CLI[agent-memory CLI]
  CLI --> Memory[memory/*.md]
  CLI --> Index[context-index.json]
  CLI --> Graph[repository-graph.json]
  Agent[AI coding agent] --> Memory
  Agent --> Index
  Agent --> Graph
  Agent --> Worklog[worklog + handoff]
  Worklog --> Next[Next agent/session]

What Gets Generated

ArtifactPurpose
AGENTS.mdAgent instructions for reading and maintaining the memory layer.
memory/context-index.jsonMachine-readable index of memory topics and files.
memory/00-project-overview.mdProject shape, languages, frameworks, quick-start commands, and ownership context.
memory/01-repository-map.mdSource, config, docs, generated, and vendor boundaries.
memory/04-api-and-interfaces.mdLikely API, route, and interface files.
memory/07-testing-and-quality.mdTest/build commands and quality gates.
memory/repository-graph.jsonStatic dependency and symbol graph, when graph build is enabled.
memory/architecture-flow.mdHuman-readable graph summary.
memory/agent-worklog.jsonlAppend-only agent checkpoints.
memory/agent-handoff.mdCurrent handoff state for the next agent/session.

Example Agent Workflow

Before editing a shared type or interface:

  1. Read AGENTS.md.
  2. Open memory/context-index.json.
  3. Open the relevant memory file, such as memory/04-api-and-interfaces.md.
  4. Query the graph:
agent-memory graph query --file src/types.ts
  1. Make the change.
  2. Run the repository's test command from memory/07-testing-and-quality.md.
  3. Record a checkpoint:
agent-memory worklog checkpoint \
  --agent codex \
  --message "updated shared interface and verified downstream tests" \
  --files src/types.ts,tests/types.test.ts \
  --commands "npm test"

Before switching agents or stopping mid-task:

agent-memory worklog handoff \
  --agent codex \
  --message "tests pass; README still needs review" \
  --next "review docs and publish release notes"

Code Graph And Blast Radius

AMS includes a headless static analysis engine that tracks symbol-level dependencies, architectural layers, and call relationships.

Build graph artifacts:

agent-memory graph build

Query the impact of a shared file:

agent-memory graph query --file src/types.ts

Check API surface changes between graph snapshots:

agent-memory graph diff

The graph is intended to give agents a better starting map before they edit high-impact files. It is static analysis, so results should still be checked against tests and code review.

Benchmarks And Reproducibility

AMS includes an early benchmark harness for testing whether repository memory changes coding-agent workflows.

The benchmark compares:

  • baseline: an agent starts from repository files only
  • AMS: an agent starts with generated memory, graph artifacts, worklog, and handoff files

Task categories include repository understanding, refactoring, debugging, recovery, and multi-agent continuity. Current results should be treated as maintainer-run measurements, not independent validation.

See:

This suggests AMS can reduce broad file traversal and improve project-concept recall when generated memory contains the relevant facts. It also shows why benchmark transparency matters: memory context has an upfront token cost, so future runs should measure when that cost pays off.

Run the current harness:

npx tsx benchmarks/scripts/run.ts --repo . --mode both
npx tsx benchmarks/scripts/report.ts

Future benchmark reports should include commit SHA, AMS version, repository fixture, agent/model version, exact prompt, raw or redacted logs, scoring rubric version, and known limitations.

Demo Plan

Planned demo assets are documented in docs/demo-assets.md. The first demo should be a short terminal recording showing:

  1. init
  2. generated memory/ files
  3. a graph query
  4. a worklog checkpoint
  5. a handoff file

Security Model

  • Documents environment variable names, never values.
  • Validates generated memory for obvious secret patterns.
  • Ignores generated and vendor paths such as node_modules/, .git/, dist/, build/, .next/, .venv/, __pycache__/, and target/.
  • Labels uncertain sections as [INFERRED], [INCOMPLETE], or [PLANNED].
  • Supports CI checks so stale memory cannot silently pass review.
  • Encourages branch protection so all changes go through pull requests and CI.

Integrations And Agent Instructions

AMS works best when the repository's agent instructions tell coding tools how to use generated memory.

Useful patterns:

  • Codex: read AGENTS.md, open the relevant memory file, and run graph queries before shared-interface edits.
  • Claude Code: use generated project memory and handoff files as repo-level context.
  • Cursor/Gemini CLI/Antigravity: include generated memory/ files as project context and update them after structural changes.

Contributing

Public contributions are welcome. Good first areas:

  • add framework and route detectors
  • improve generated memory templates
  • add graph parser coverage
  • improve benchmark fixtures
  • add integration docs for coding agents
  • improve examples and docs

Before opening a pull request:

npm install
npm run typecheck
npm test
npm run build
npm run memory:check

PRs that change generated memory shape should include before/after examples. Changes to main should go through pull requests with the Required CI status check passing.

Project Status

AMS is early. The core CLI is usable, but benchmark methodology, graph coverage, and agent-specific integrations are still evolving. The project favors reviewable artifacts and deterministic scanning over hidden model calls.

Ownership

Support ongoing open-source development:

License

MIT