How I Gave My AI Agents a Permanent Memory That Syncs Across Machines

If you've spent any time working with AI coding agents like Claude Code, you've probably noticed the elephant in the room: every session starts from scratch. Your agent debugs a tricky deployment issue, discovers that your project needs a specific environment variable, figures out the architecture of your codebase — and then forgets all of it the moment the session ends.

The next session? Back to square one.

I built agent-knowledge to fix this. It's an open-source MCP server that gives AI agents a persistent, git-synced memory — a knowledge base they can read from and write to across sessions, across machines, and across different AI clients.

The Problem: Ephemeral Agent Sessions

When you're working with Claude Code (or any AI coding agent), the conversation is stored as a JSONL transcript file — but the agent itself can't search or learn from previous sessions. Every new session is a blank slate.

This means you end up repeating yourself constantly. You re-explain your project structure. You re-describe team preferences. You re-debug the same issues. It's like working with a brilliant colleague who has amnesia.

The Solution: Two Complementary Memory Systems

agent-knowledge tackles this with two systems working together:

Knowledge Base — A git-synced markdown vault where structured entries live. Think of it as a shared wiki that your agent can read and write. Entries are organized into categories like projects, decisions, workflows, people, and notes. Each entry is a markdown file with YAML frontmatter, and every write is automatically committed and pushed to git.

Session Search — TF-IDF ranked full-text search across all your past session transcripts. Instead of those JSONL files just sitting on disk, they become a searchable archive. Your agent can look up what happened in previous sessions — what errors occurred, what decisions were made, what files were modified.

How It Works Under the Hood

The architecture is straightforward. agent-knowledge runs as an MCP server over stdio, exposing 12 tools that your AI client can call. It also auto-starts a dashboard on localhost:3423 for browsing everything visually.

On the knowledge side, markdown files live in a git repository (by default at ~/claude-memory). Every read triggers a git pull, every write triggers a git add, commit, and push. This means if you're working on two machines, your knowledge stays in sync automatically.

On the session search side, it parses the JSONL transcript files that Claude Code generates and builds a TF-IDF index over them. The index is cached for 60 seconds and rebuilt on demand. Individual files are cached based on their modification time so unchanged files are never re-parsed.

There's also a scoped recall system with six predefined filters: errors (stack traces, exceptions), plans (architecture, TODOs), configs (settings, env vars), tools (MCP calls, CLI commands), files (paths, modifications), and decisions (trade-offs, rationale). This lets your agent ask targeted questions like "what errors have I seen in this project before?"

Getting Started

Setup is simple:

git clone https://github.com/keshrath/agent-knowledge.git

cd agent-knowledge

npm install && npm run build

Then register it as an MCP server in Claude Code:

claude mcp add agent-knowledge -s user \

  -e KNOWLEDGE_MEMORY_DIR="$HOME/claude-memory" \

  -- node /path/to/agent-knowledge/dist/index.js

And grant permissions in your ~/.claude/settings.json:

{

  "permissions": {

    "allow": ["mcp__agent-knowledge__*"]

  }

}

That's it. Open http://localhost:3423 in your browser and you'll see the dashboard with four tabs: Knowledge, Search, Sessions, and Recall.

Works With Claude Code and OpenCode

agent-knowledge works with any MCP client over stdio. The setup guide includes configuration examples for both Claude Code and OpenCode.

Claude Code gets the richest experience with lifecycle hooks and session auto-distillation. You can set up a SessionStart hook that announces the knowledge dashboard URL at the beginning of every session, so the agent always knows where to look.

OpenCode supports MCP servers through its opencode.json config and offers lifecycle hooks via its plugin system. You can wire up events like session.created and tool.execute.after to integrate agent-knowledge into your workflow.

Both clients support the full set of 12 MCP tools — knowledge CRUD, session search, scoped recall, and admin configuration.

The Dashboard

The built-in web dashboard is a vanilla JS single-page app — no framework, no build step. It connects over WebSocket for live updates and supports light/dark theming with Material Design 3 tokens.

The Knowledge tab shows a card grid of your entries, filterable by category. The Search tab gives you full-text search with TF-IDF ranking and role filtering. The Sessions tab lists all your past conversations with project names and git branches. And the Recall tab lets you do scoped searches to quickly find errors, plans, or decisions from your history.

There's even a live reload feature for development — edit the UI files and connected browsers auto-refresh.

Auto-Distillation and Secrets Scrubbing

Two features that stood out to me: auto-distillation and secrets scrubbing.

Auto-distillation automatically extracts insights from completed sessions and pushes them to the knowledge base. Instead of manually curating what the agent learned, it happens automatically.

Secrets scrubbing ensures that API keys, tokens, passwords, and private keys are redacted before anything gets pushed to git. This is critical — you don't want your agent accidentally committing sensitive data to a shared repository.

Why This Matters

AI coding agents are incredibly powerful, but the lack of persistent memory has been a major friction point. Every time you start a new session, there's a ramp-up cost. The agent needs to re-learn your project, your preferences, your past decisions.

agent-knowledge eliminates that ramp-up. Your agent remembers what it learned, can search its own history, and shares knowledge across machines and sessions. It turns ephemeral conversations into a cumulative knowledge base that grows over time.

If you're using AI coding agents seriously, give agent-knowledge a look. It's MIT licensed, well tested, and the documentation is thorough. Check out the architecture docs if you want to understand how the internals work, or jump straight to the setup guide to get started.

Have you been dealing with the same "amnesia" problem with your AI agents? I'd love to hear what approaches you've tried. Drop a comment below!