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, a hybrid local MCP runtime is the public agent interface, and the dashboard lets a human approve, edit, protect, or remove what agents remember. Agent commands work without a background server. The authenticated localhost server starts on demand for the dashboard and can optionally run continuously for live file watching and shared embedding work.

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.

How it compares

Use project instruction files for compact rules that always belong in a prompt. Use Global Agent Memory when knowledge should be searchable, shared between clients, reviewed by a person, updated over time, or hidden behind explicit permission.

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.
• No required background server: Claude Code, Codex, and CLI commands fall back to the same MCP application services in-process when the optional daemon is offline.
• Local security boundary: when the dashboard or HTTP MCP is active, the server binds to 127.0.0.1 and requires a generated bearer token stored outside the Vault.

Built for real project vaults

The opt-in performance suite creates 10,000 synthetic memories and exercises the same indexing and retrieval paths used by both runtime modes. On the recorded macOS ARM64 baseline, a full rebuild takes 36.5 seconds, warm keyword search P95 is 56 ms, warm hybrid search P95 is 76 ms, and incremental stdio proxy overhead is 1.5 ms. Results vary by machine; the changed-note, search, and proxy budgets run as regression gates. See the methodology and complete baseline.

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

This is the shortest path to persistent memory for Claude Code, Codex, and other MCP clients. The guided installer creates the local service, Obsidian-compatible Vault, dashboard, MCP registrations, and agent skills together.

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 global-memory-mcp

To install the latest unreleased source, use uv tool install git+https://github.com/ozankasikci/global-agent-memory.git. For a local checkout, use uv tool install ..

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, detects Claude Code and Codex, installs their MCP integrations and skills, verifies healthy clients, and opens the dashboard. Opening the dashboard starts its authenticated localhost server on demand. 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

# Optional: install an always-on native service for live watching and shared indexing
global-memory setup --service

# 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: