Building common-knowledge: Persistent Memory for Agents

common-knowledge is a Git-backed memory store I built so AI coding agents (Claude Code, Cursor, Cline) keep context across sessions and projects. Open source. Cross-platform. Offline-friendly. Here's the design.

The problem

Every Claude Code session starts cold. You explain the project, the conventions, what you tried last time. After 50 sessions you are explaining the same thing 50 times. The agent forgets; you compensate.

common-knowledge is the layer that fixes that.

The design

A local Git repo per project. Each note is a markdown file. Each save is a Git commit with a descriptive message. The agent reads relevant notes at the start of every session; it writes new notes when it learns something.

~/.common-knowledge/<project>/
  decisions/
    auth-uses-jwt.md
    redis-for-cache.md
  context/
    onboarding.md
  conventions/
    error-handling.md

Why Git

Three reasons:

Versioning is free. Every note has full history. Roll back a bad decision.
Sync is free. Push to a private GitHub repo; pull from another machine.
The format is durable. Plain markdown + Git outlives any custom DB I could build.

I went deeper on similar patterns in Building Context-Heavy (knowledge graph for agents, but stored differently).

How agents use it

The agent looks up relevant notes when planning a task. It writes a new note when it makes a non-obvious decision. The CLI is the integration surface:

ck save "decided to use jwt for auth" --project myapp
ck load --project myapp
ck search "auth" --project myapp

What I learned shipping it

Plain text wins. No DB, no schema migration. Markdown is the right format.

Commits as semantic events. git log becomes a narrative of "what did we learn." That's an unexpected value.

Offline is the killer feature. No cloud dependency means it works on a flight, in a power outage, behind a corporate firewall.

What's next

A web UI for browsing notes across projects, and a "review my notes" command that lets the agent self-audit decisions for staleness.

My AI Agent Skills Stack covers how common-knowledge sits alongside the other open-source skills I maintain.

FAQ

Q: Where is the source? A: github.com/shihabshahrier/common-knowledge.

Q: Does it work with non-Claude agents? A: Yes — anything that can run a CLI. Cursor and Cline pick it up.

Q: How is this different from a vector DB? A: A vector DB is for similarity over documents you don't author. common-knowledge is for decisions and conventions you author and revisit.

Built by Shihab Shahriar Antor. More open source: softco, skill-builder. Hire me.