Global Agent Memory

Local-first, project-aware, durable memory for Claude Code, Codex, and other
MCP-compatible agents.

Global Agent Memory gives multiple coding agents one shared, reviewable memory without
handing control of your knowledge base to a hosted service. Markdown files are
canonical, an authenticated local MCP daemon is the public agent interface, and the
dashboard lets a human approve, edit, protect, or remove what agents remember.

One Vault. Multiple agents. Human-controlled memory.

Quick start · Obsidian Vault ·
Dashboard · How it works ·
Security · MCP contract · Documentation

Why Global Agent Memory?

Coding agents are useful inside a session, but important context is often lost between
sessions or fragmented across individual clients. Global Agent Memory provides a durable
layer for knowledge such as:

• architectural decisions and project conventions;
• verified workflows and operational runbooks;
• recurring problems and their proven solutions;
• project preferences, entities, and handoff summaries;
• bounded context for a new task or agent session.

Agents propose memories as candidates. A human reviews them before they become
durable, controls their visibility, and can later update, supersede, archive, or
hard-delete them.

Highlights

• Shared across agents — Claude Code, Codex, and other MCP clients use the same
  service and immutable memory IDs.
• Project-aware by default — Git roots, remotes, aliases, and the project registry
  keep retrieval scoped to the active project.
• Markdown is canonical — the Vault remains readable, portable, backup-friendly, and
  usable with Obsidian.
• Human review workflow — agents create candidates; owners approve, edit, reject, or
  resolve conflicts in the dashboard.
• Protected and sealed memory — sensitive knowledge can be excluded from ordinary
  retrieval and placed behind owner-controlled access.
• Hybrid local search — SQLite FTS5 provides keyword retrieval; optional Ollama
  embeddings and sqlite-vec add semantic ranking.
• Offline-friendly — keyword search and lifecycle operations continue when Ollama is
  unavailable.
• Rebuildable generated state — SQLite, FTS, vectors, queues, and caches can be
  recreated from Markdown.
• Frozen MCP V1 contract — tools, resources, prompts, envelopes, and compatibility
  rules are versioned in the repository.
• Local security boundary — the daemon binds to 127.0.0.1 and requires a generated
  bearer token stored outside the Vault.

Three surfaces, one memory system

Global Agent Memory is more than an MCP server. Agents, owners, and knowledge workers
use the same canonical memories through three purpose-built surfaces:

The Vault is the durable source of truth. The dashboard is a complementary control
plane, and the MCP interface is the safe automation layer used by agents. You can use
Obsidian, the dashboard, or both without creating separate copies of your memory.

Dashboard at a glance

_{Real dashboard UI with synthetic Atlas project data. No private Vault content is shown.}

Quick start

Requirements

• macOS or Linux
• Python 3.12 or newer
• uv
• Claude Code or Codex for the managed client integrations
• Optional: Obsidian for browsing the Markdown Vault
• Optional: Ollama for semantic retrieval

1. Install

uv tool install git+https://github.com/ozankasikci/global-agent-memory.git

For a local checkout, use uv tool install . instead.

2. Run guided setup

global-memory setup

Setup shows one plan and asks once before it changes anything. It initializes the local
Vault, creates the protected token, installs and starts the native per-user service,
detects Claude Code and Codex, installs their MCP integrations and skills, verifies
healthy clients, and opens the dashboard. The command is idempotent, so running it again
repairs or updates managed components without replacing unrelated client configuration.

Use flags when you need a non-default setup:

# Non-interactive installation
global-memory setup --yes

# Choose a different Vault on first setup
global-memory setup --vault "$HOME/Memory"

# Install only one client, or no client yet
global-memory setup --clients claude-code
global-memory setup --clients none

# Preview without changing files or services
global-memory setup --dry-run

3. Use the installed agent shortcuts

Setup installs five basic shortcuts for each detected client:

In Claude Code, invoke them directly, for example /gam-context fix the upload retry bug.
In Codex, type /skills and choose one, or mention it directly, for example
$gam-context fix the upload retry bug.

4. Open the dashboard again

global-memory dashboard

You can also ask a connected agent:

Open the Global Agent Memory dashboard.

The agent calls memory_dashboard_open and opens the same authenticated local
dashboard.

Manual installation and repair

The individual commands remain available for advanced setups and troubleshooting:

global-memory init --vault "$HOME/Documents/Global Agent Memory"
global-memory daemon install-service --kind launchd  # use systemd on Linux
global-memory integrations install all
global-memory integrations verify all
global-memory doctor

Using it with an agent

After integration, you normally describe your intent instead of running memory commands
manually.

Retrieve context before work

Before you start, load the relevant memory for this project and summarize the
conventions and recent decisions.

Propose a durable memory

Remember that production ARM64 binaries must be built locally and uploaded to the
server. Add it as a project convention with the deployment discussion as evidence.

The agent creates a candidate. Nothing becomes active until it is approved.

Update existing knowledge

Find the deployment memory and update it with the new health-check command. Do not
create a duplicate.

Open the review surface

Open the memory dashboard so I can review the candidates.

The shared integration skill teaches supported agents when to retrieve, propose, update,
and avoid duplicating memory.

Obsidian Vault

The configured Obsidian Vault is the human-readable, durable source of truth—not an
export of an opaque database. Every managed memory is a normal Markdown file with YAML
properties, a stable memory ID, lifecycle metadata, and project-aware links.

Initialization adds an Obsidian workspace without replacing your existing files:

• templates for decisions, facts, solutions, conventions, preferences, entities,
  references, session summaries, and project overviews;
• native Bases views for the candidate review queue, active knowledge, recent updates,
  decisions by project, verified solutions, and lifecycle history;
• project overview hubs that embed project memories and remain stable as notes move
  through candidate, active, rejected, superseded, or archived folders;
• wikilinks and reciprocal supersession links for backlinks and graph navigation;
• watcher synchronization, so ordinary content and descriptive-property edits made in
  Obsidian become searchable without restarting the service.

Obsidian is optional: the same Markdown remains readable and editable with any text
editor. Lifecycle and access-policy changes should still go through the dashboard, MCP,
or CLI so validation, optimistic concurrency, and audit records remain intact.

Dashboard

The authenticated dashboard is the owner control plane for:

• project overview and recent project activity;
• one-at-a-time candidate review and editing;
• duplicate and conflict comparison;
• memory search and lifecycle management;
• Standard, Protected, and Sealed classification;
• access-request approval and active-grant revocation;
• sealed-memory owner unlocks with audit records;
• project switching, system health, reindexing, and backups;
• opening canonical Markdown in Obsidian or the local file viewer.

_{Candidate review keeps evidence and conflicts visible before an owner approves durable memory.}

Dashboard launch URLs expire after 60 seconds, can be exchanged only once, and create a
local HttpOnly session. Do not share a launch URL.

Memory visibility and access

Protected grants are scoped by purpose, project, agent, permission, exact memory IDs,
and duration. Owners may downgrade a request but never elevate it. Agents may request
and poll for access, but they cannot approve, deny, or revoke grants.

[!IMPORTANT]

Protected and Sealed memory are not secret managers. Never store passwords,
credentials, private keys, API keys, or bearer tokens in Global Agent Memory.

How it works

flowchart LR
    A[Claude Code] -->|stdio MCP proxy| D[global-memoryd]
    B[Codex] -->|stdio MCP proxy| D
    C[Other MCP clients] -->|Streamable HTTP| D

    D --> E[Application and domain services]
    E --> V[Markdown Vault<br/>canonical state]
    E --> I[SQLite FTS5 and sqlite-vec<br/>generated state]
    E --> O[Ollama embeddings<br/>optional]
    E --> W[Local dashboard<br/>owner control]

The daemon is the single owner of the Vault watcher, generated indexes, embedding queue,
and MCP transport. Streamable HTTP clients connect directly on localhost; stdio-only
clients launch the thin global-memory-mcp proxy. Both paths expose the same MCP V1
contract.

The dependency direction is:

transport and client adapters → application services → domain

Vault, SQLite, vectors, embeddings, Git, Watchdog, and client integrations are adapters.
The domain layer does not depend on them.

MCP interface

The MCP interface is the only public AI-facing API. Clients do not read the Vault,
SQLite database, vectors, token, or runtime logs directly.

The frozen V1 discovery snapshot currently contains 17 tools, 10 resources, and
6 prompts.

All mutations are replay-safe through request_id. Updates use optimistic concurrency,
and a stale version fails with VERSION_CONFLICT instead of silently overwriting newer
knowledge.

See MCP Contract V1 and the generated
contracts/mcp/v1/ schemas for the complete contract.

CLI examples

The CLI uses the same MCP path as connected agents; it does not bypass the daemon to
read generated state.

# Check health
global-memory status
global-memory doctor

# Register and detect a project
global-memory project add my-project --root "$HOME/Projects/my-project"
global-memory project detect "$HOME/Projects/my-project"

# Search and build bounded task context
global-memory search "deployment rollback" --project my-project
global-memory context "Prepare the next release" --project my-project --token-budget 3000

# Create a review candidate
global-memory remember \
  "Release rollback procedure" \
  "Use the blue-green rollback task and verify both health endpoints." \
  --type reference \
  --scope project \
  --project my-project

# Rebuild generated indexes
global-memory reindex --full

# Back up canonical Markdown
global-memory backup "$HOME/Backups/global-agent-memory.zip"

Run global-memory --help or global-memory <command> --help for the complete command
reference.

Security model

Global Agent Memory is designed as a local service, not a remotely exposed memory API.

• The daemon is restricted to 127.0.0.1.
• Streamable HTTP requires a generated local bearer token.
• The token, database, logs, locks, and generated state remain outside the Vault.
• Token files use user-only permissions.
• Dashboard sessions are short-lived, local, and HttpOnly.
• Paths are confined to the configured Vault and checked against traversal and symlink
  escape.
• Ordinary logs redact bodies, prompts, embeddings, secrets, and authorization material.
• Generated state can be removed and rebuilt from canonical Markdown.
• Agent-facing retrieval is fail-closed for Protected and Sealed memories.

Please report security issues according to SECURITY.md.

Development

Clone the repository, then install Python and dashboard dependencies:

uv sync
npm ci --prefix dashboard

Run the standard quality gate:

make check

The gate covers Ruff formatting and linting, strict MyPy, the TypeScript production
build, unit/integration/contract/E2E tests, coverage, and deterministic MCP contract
regeneration.

Useful focused commands:

make unit
make integration
make contract
make e2e
make dashboard-check
make performance   # opt-in 10,000-note performance suite

When changing the MCP contract:

make contract-generate
make contract-check

Contributions are welcome. Start with CONTRIBUTING.md, and keep
changes compatible with the frozen V1 contract unless a parallel major contract is
intentionally introduced.

Documentation

Project status

Global Agent Memory is under active V1 development and is currently intended to be
installed from source. The package version is 0.1.2; the MCP contract version is v1.

The product name is Global Agent Memory. The technical identifiers global-memory,
global-memory-mcp, global-memoryd, global_memory, and product: global-memory
remain stable for V1 compatibility.

See the V1 release checklist for verified scenarios and
remaining live acceptance work.

License

Global Agent Memory is available under the MIT license declared in
pyproject.toml.