elephagent 0.1.2

Shared memory layer for all your AI coding agents — elephants never forget

elephagent

One memory layer for all your AI coding agents — elephants never forget.

English | 中文

---

The Problem

You use Claude Code, Cursor, and Codex. Each stores project knowledge in a different place. Switch machines, add a teammate, or try a new agent — and you start from scratch.

	Without elephagent	With elephagent
Memory location	Scattered across CLAUDE.md, .cursor/rules/, AGENTS.md	One .agent/ directory, auto-synced to all platforms
Switch tools	Re-teach every agent from scratch	All agents share the same memory instantly
New teammate	Copy-paste tribal knowledge	git clone and everything is there
MCP servers	Configure separately in each tool	Register once, available everywhere

How It Works

elephagent stores everything in one Git-synced .agent/ directory and renders the config files each tool already knows how to read. Your AI agents can also read and write memory directly via a built-in MCP server.

flowchart LR
    subgraph repo["Your Repository"]
        direction TB
        src[".agent/\n─────────────\nmemory/\n  decisions.md\n  workflows.md\n  pitfalls.md\ntools/\n  registry.json"]
    end

    src -->|"elephagent build"| CLAUDE["CLAUDE.md\n(Claude Code)"]
    src -->|"elephagent build"| AGENTS["AGENTS.md\n(Codex)"]
    src -->|"elephagent build"| CURSOR[".cursor/rules/\n(Cursor)"]
    src -->|"elephagent build"| MCP[".mcp.json\n(all clients)"]

    CLAUDE --> cc["Claude Code"]
    AGENTS --> codex["Codex"]
    CURSOR --> cursor["Cursor"]
    MCP --> cc
    MCP --> codex
    MCP --> cursor

    cc -->|"/remember"| src
    cursor -->|"/remember"| src
    codex -->|"/remember"| src

---

Installation

pip install elephagent

Or with pipx (recommended for global CLI tools):

pipx install elephagent

---

Quick Start

Option A — Just talk to your AI agent (recommended)

If you use Claude Code or Cursor, you don't need to type any commands. Just say:

What you say	What happens
init memory	Sets up .agent/ and generates all platform files
/remember <note>	Saves a note to shared memory (use the slash command)
sync memory	Commits and pushes memory to Git
check memory	Runs a health check on the setup
add skill <name>	Creates a new shared skill

Note: Use /remember as a slash command rather than natural language — phrases like "remember this" may be intercepted by the AI agent's built-in memory system.

Option B — CLI

# Initialize in your project (auto-runs `git init` if needed)
elephagent init

# Add a memory note
elephagent remember "This repo uses pnpm. Redis is required for API tests."

# Rebuild all adapter files
elephagent build

# Verify the setup
elephagent doctor

# Commit and push memory to Git
elephagent sync -m "update memory"

---

Platform Setup

After running elephagent init, each platform picks up its config automatically — with one exception:

Platform	Generated files	Extra steps
Claude Code	CLAUDE.md, .mcp.json	None — works out of the box
Cursor	.cursor/rules/, .cursor/mcp.json	Open the project folder in Cursor — it auto-detects the agent-memory MCP server. Enable it in Settings → Cursor Settings → MCP if prompted
Codex	AGENTS.md, .codex/config.toml	None — works out of the box

---

Built-in Skills

elephagent ships five skills that work across Claude Code, Cursor, and Codex — no commands needed.

Skill	Trigger phrases	What it does
/init-memory	"init memory", "set up agent memory"	Bootstrap .agent/ and generate platform files
/remember	/remember <note> (slash command)	Save a note from the conversation to shared memory
/check-memory	"check memory", "memory status", "doctor"	Health-check the memory setup
/sync-memory	"sync memory", "push memory"	Build → commit → push to Git
/add-skill	"add skill <name>"	Create a new shared skill

---

All CLI Commands

Command	Description
elephagent.py init	Bootstrap .agent/ and generate all platform files
elephagent.py remember "..."	Append a note and rebuild
elephagent.py build	Regenerate all adapter files from .agent/
elephagent.py doctor	Check that everything is in sync
elephagent.py sync -m "msg"	Build → pull → commit → push
elephagent.py tool list	List registered MCP servers
elephagent.py tool add <name>	Register a new MCP server

Adding MCP tools

# stdio server
python3 elephagent.py tool add context7 --command npx --arg -y --arg @upstash/context7-mcp

# HTTP server with token from env
python3 elephagent.py tool add figma \
  --url https://mcp.figma.com/mcp \
  --bearer-token-env-var FIGMA_OAUTH_TOKEN

---

Built-in MCP Server

elephagent ships a small MCP server at .agent/tools/mcp_server.py that lets agents read and write shared memory directly through the MCP protocol.

Tool	Description
agent_memory_read	Read one or all memory files
agent_memory_search	Search across all memory
agent_memory_append	Append a durable note
agent_tool_registry	Read the shared MCP registry

---

Why Git?

• Memory travels with the repo, not the machine.
• Works in CI, on new laptops, with new teammates.
• Full history and diffs for every memory change.
• No third-party service required.

---

Security

Never commit secrets into .agent/. Use environment variable references instead:

python3 elephagent.py tool add internal-api \
  --url https://example.com/mcp \
  --bearer-token-env-var INTERNAL_API_TOKEN

.agent/.gitignore excludes local scratch files and secret-looking filenames by default.

---

Roadmap

• Git-synced shared memory
• Auto-generated adapters for Claude Code, Cursor, Codex
• Built-in MCP server
• Shared MCP tool registry
• Built-in skills for Claude Code, Cursor, Codex
• Python SDK (import elephagent)
• Importers for existing Claude / Cursor / Codex memories
• Memory compaction for large histories
• pipx / Homebrew packaging
• GitHub Action for CI validation

---

Contributing

Issues and PRs are welcome. Before submitting, run:

python3 elephagent.py build
python3 elephagent.py doctor
python3 - <<'PY'
from pathlib import Path
for path in ["elephagent.py", ".agent/tools/mcp_server.py"]:
    compile(Path(path).read_text(), path, "exec")
    print(path, "ok")
PY

---

License

MIT