Agent Memory

Persistent memory for agent platforms with separate global and project scopes.

agent-memory helps Codex and Claude Code retain durable knowledge without turning every session into prompt archaeology. It gives the model a structured way to store and retrieve:

• user preferences and long-lived behavior rules
• cross-project coding patterns
• repository-specific workflows and conventions
• deployment notes, redacted credential locations/processes, setup steps, and operational gotchas

This package backs the standalone Agent Memory plugin.

Highlights

• global memory stored under ~/.agents/.wiolett/global-memory/ by default
• project memory stored under <repo>/.memory/
• deep canonical memories plus a separate lightweight index layer
• semantic and keyword search
• meaningful memory filenames
• weighted, typed graph links between deep memories and standalone lite memories
• automatic graph-link suggestions on save/update without touching manual links
• graph-expanded memory_query: surfaces edge-connected memories the query text missed
• supersede/duplicate detection on save: contradicting memories get a supersedes edge and are downranked (never deleted)
• pathfinding between two memories and read-only graph health metrics + auto-edge pruning
• sanity-gated saves and stable in-place memory updates
• compiled recall/query answers and broad multi-memory recaps with source references
• automatic project-memory setup on write/mutation use; reads stay no-op when project memory is absent

Memory Scopes

Global Memory

Global memory is for information that should follow the user across repositories:

• response style preferences
• coding habits and tool choices
• cross-project requirements for model behavior
• reusable personal workflows

Global memory is available through canonical tools with scope: "global". Some compatibility helpers and graph maintenance helpers also use global_memory_* names.

Project Memory

Project memory is for repository-specific knowledge:

• setup and bootstrap steps
• deployment and release workflows
• project conventions
• undocumented dependencies
• redacted credential locations/processes and environment-specific instructions

Project memory auto-initializes on write/mutation use in a repository. Read tools do not create .memory/ when project memory is absent; they return empty results instead.

Storage Model

Global memory:

~/.agents/.wiolett/global-memory/
  memories/
  index/
  embeddings/
  graph/
  memory.db

Project memory:

.memory/
  memories/
  index/
  embeddings/
  graph/
  memory.db
  memory.db-shm
  memory.db-wal

Canonical markdown memory files, index files, embedding arrays, and graph files are the source of truth and should be committed for project/team memory. SQLite is used as local cache for fast lookup, so only .memory/memory.db* belongs in .gitignore.

Tool Surface

Canonical tools:

• memory_save
• memory_update
• memory_recall
• memory_query
• memory_recap
• memory_list
• memory_inspect
• memory_delete
• memory_link
• memory_unlink
• memory_graph
• memory_path
• memory_graph_prune
• memory_setup

Every canonical tool except memory_setup accepts an optional scope of project or global; project is the default. Project-scoped canonical tools and project compatibility aliases also accept an absolute workspace_root so callers can target a repo when the MCP server cwd differs from the workspace. memory_setup initializes or repairs project memory for the current repo or supplied workspace_root.

Graph tools:

• memory_graph reads neighbors or a bounded subgraph for one memory
• memory_path finds a path between two memories (strategy: shortest | strongest)
• memory_inspect with view: "health" returns graph metrics (orphans, dangling edges, hubs, relation distribution, weight histogram, dead pointers)
• memory_graph_prune removes unhealthy auto edges (dangling and/or below a weight floor); manual edges are never touched and it defaults to a dry run

memory_path and memory_graph_prune also have global_-prefixed variants bound to global scope.

Compatibility aliases remain available until the bundled skills move to the new names:

• memory_write / global_memory_write
• memory_get / global_memory_get
• memory_search / global_memory_search
• memory_read_lite / global_memory_read_lite
• memory_read_all / global_memory_read_all
• global_memory_delete
• global_memory_link
• global_memory_unlink
• memory_neighbors / global_memory_neighbors
• memory_subgraph / global_memory_subgraph

Normal reads should use:

• memory_recall for one compiled memory context
• memory_query for a query-aware answer synthesized from several ranked search results
• memory_recap for broad task startup or compaction recovery across several current memories
• memory_list({ index_only: true }) for lightweight index browsing; omit index_only to include deep memories as well

memory_inspect is intentionally raw and meant for maintenance/debugging.

Install

Register the Wiolett marketplace in Codex or Claude Code:

codex plugin marketplace add wiolett-industries/marketplace

/plugin marketplace add wiolett-industries/marketplace

Then install agent-memory from that marketplace in your agent platform.

Model access uses Agent Memory's built-in OpenAI-compatible auth resolver. Configure it with:

npx -y @wiolett/agent-memory@latest init

The init command creates English-commented YAML under:

~/.agents/.wiolett/config/ai-providers.yml
~/.agents/.wiolett/config/mcp-config.yml

Agent Memory is the only writer and migrator for these files. Workflow and Merge Request Review read their artifact paths from mcp-config.yml and use their built-in defaults when it is absent. A provider entry looks like:

version: 1
providers:
  openai:
    driver: openai
    base_url: https://api.openai.com/v1
    auth:
      api_key: sk-proj-...
    apis:
      responses:
        path: /responses
        store: false
      chat_completions:
        path: /chat/completions
      embeddings:
        path: /embeddings

Text roles may use either Responses or Chat Completions. Embeddings, the write gate, and synthesis can route to different named providers and models in mcp-config.yml. The provider file is written with 0600 permissions.

On either MCP startup or agent-memory init, the same locked idempotent bootstrap migrates the legacy auth-config.json and moves ~/.agents/agent-memory to the configured global path. The legacy memory path becomes a compatibility symlink and the original directory is retained as a timestamped backup.

Without an API key, model-gated writes and semantic search are disabled. Memory still falls back to keyword/FTS plus graph relations where possible.

Usage

At conversation start or before non-trivial repository work, the bundled skill first decides whether durable context can change the task. It uses one focused query for a specific question or a recap for broader recovery:

memory_query(scope="project", workspace_root="/path/to/repo", query="What prior decisions affect this change?")
memory_recap(scope="project", workspace_root="/path/to/repo", topic="release and deployment context")

When a repository should use project memory, save or mutate project memory normally. The first write/mutation call initializes the local .memory/ store automatically. Read calls against a repo with no project memory return empty results and leave the repo untouched. After a repo root is known, pass an absolute workspace_root on project-scoped reads/writes if the MCP server may have launched from another directory.

From there, use memory tools to store and retrieve reusable knowledge as needed.

Example canonical calls:

memory_save(content="Project releases use pnpm build before publish.", tags=["release", "pnpm"])
memory_query(query="How do releases work?")
memory_recap(topic="release and deployment context")
memory_list(scope="project", workspace_root="/path/to/repo", index_only=true)
memory_recall(memory_id="abc123xy")
memory_inspect(view="all")

View — local dashboard

agent-memory view opens a read-only control panel for a memory store in your browser. It boots a loopback-only HTTP server (127.0.0.1) that serves a prebuilt SPA plus a small JSON API, reading the same files the MCP server uses.

Run it with npx (no install needed):

npx -y @wiolett/agent-memory@latest view                # current dir's ./.memory
npx -y @wiolett/agent-memory@latest view ./some/project # that project's .memory
npx -y @wiolett/agent-memory@latest view global         # the global store

Or, if the package is installed, use the agent-memory bin directly:

agent-memory view                 # current directory's ./.memory
agent-memory view ./some/project  # that project's .memory
agent-memory view global          # the configured global store

Options:

• --port <n> — preferred port (default 7077; auto-increments if taken)
• --no-open — do not launch the browser automatically

Panels:

• Graph — force-directed view of memories and their links; filter by relation, manual/auto source, and weight; click a node for its content, tags, and neighbors. Superseded memories are dimmed.
• Memory — searchable list of every memory and index entry.
• Health — graph metrics (orphans, dangling edges, hubs, weight histogram, dead pointers) mirroring memory_inspect view=health.
• Query — run search and graph-expanded query side by side and see how results are scored and graph-connected.
• Path — trace the shortest or strongest path between two memories and highlight it on the graph.
• Scatter — 2D PCA projection of memory embeddings (needs an embedding provider and at least two embedded memories).

The dashboard is read-only and live: editing a .md or graph file on disk refreshes the open panel automatically. The server is lazy-loaded, so running the MCP server never pays for the UI. Nothing is sent off the machine.

Development

Requirements:

• Node.js 22.5+
• optional provider credentials in ~/.agents/.wiolett/config/ai-providers.yml for model-gated writes, semantic search, and AI-generated memory slugs

Useful commands:

pnpm typecheck
pnpm build
pnpm test