_SH Log's
← Back to Root
EST: 5 min read

Building common-knowledge: Persistent Memory for AI Agents

common-knowledge is a Git-backed memory store I built so AI agents keep context across sessions. Here's the design and why Git is the right storage backend.

#ai-agents#open-source#claude-code#productivity

AI coding agents forget everything when a session ends. Every new session starts cold — re-explaining the architecture, re-establishing project context, re-discovering the same gotchas. common-knowledge is my solution: a Git-backed knowledge store that agents can read and write across sessions.

The problem with stateless agents

A typical coding session:

Session 1 (2 hours):
- Established: auth middleware must run before CORS in Chi
- Discovered: pgBouncer in session mode breaks prepared statements
- Decided: use UUID v7 for all new IDs (sortable)

Session 2 (next day):
- Spent 30 minutes re-discovering the CORS/auth middleware order
- Tried prepared statements, broke pgBouncer, re-discovered the issue

This is pure waste. The agent isn't dumb — it just doesn't remember. common-knowledge gives it persistent memory.

Why Git as storage backend

I evaluated several options:

| Option | Problem | |--------|---------| | SQLite | Not human-readable, harder to diff, no VCS | | Redis | Volatile, no history, expensive for persistence | | Local JSON files | No VCS, hard to search, no conflict resolution | | Git + Markdown | ✅ Readable, diffable, searchable, versioned |

Git gives you three things for free: history (every save is a commit), diffing (see what changed), and conflict resolution (if two agents write simultaneously). Markdown gives you human readability — you can cat a memory file and understand it instantly.

Data structure

~/.ck/
├── projects/
│   ├── letx/
│   │   ├── architecture.md
│   │   ├── gotchas.md
│   │   ├── decisions.md
│   │   └── progress.md
│   └── quantumsketch/
│       ├── architecture.md
│       └── gotchas.md
├── global/
│   ├── go-patterns.md
│   ├── aws-setup.md
│   └── lessons.md
└── schema.json  # metadata index

Each file is plain Markdown. The schema.json is a lightweight index for fast search without reading every file.

CLI interface

# Save a lesson
ck save "auth middleware must run before CORS in Chi router"
ck save --project letx "pgBouncer session mode breaks prepared statements"

# Load project context
ck load letx          # prints all letx knowledge to stdout (for agent context)

# Search across all knowledge
ck search "middleware order"
ck search --project letx "database"

# Show what's saved
ck status
ck map                 # visual tree of all knowledge

# Ingest documents
ck ingest architecture.pdf
ck ingest decisions.csv

Implementation: the save command

def save(text: str, project: str = None, tags: list = None):
    """Save a piece of knowledge with automatic categorization."""
    # LLM categorizes the knowledge
    category = classify_knowledge(text)  # gotcha/decision/architecture/lesson
    
    # Determine target file
    if project:
        path = CK_DIR / "projects" / project / f"{category}.md"
    else:
        path = CK_DIR / "global" / f"{category}.md"
    
    # Append with timestamp
    path.parent.mkdir(parents=True, exist_ok=True)
    with open(path, "a") as f:
        f.write(f"\n## {datetime.now().isoformat()[:10]}\n")
        f.write(f"{text}\n")
        if tags:
            f.write(f"Tags: {', '.join(tags)}\n")
    
    # Git commit
    repo = Repo(CK_DIR)
    repo.index.add([str(path)])
    repo.index.commit(f"ck: save {'[' + project + '] ' if project else ''}{text[:60]}")
    
    print(f"Saved to {path}")

The LLM categorization is optional but useful — it routes "pgBouncer breaks prepared statements" to gotchas.md rather than decisions.md without requiring the user to specify.

Agent integration

In Claude Code, I start every session with:

/ck load [project-name]

This prints all saved knowledge for the project into the agent's context. The agent immediately knows:

  • The architecture decisions made previously
  • Known gotchas (don't do X because Y)
  • Progress on in-flight work
  • Patterns that work in this codebase

At the end of a session, I tell the agent to save anything notable:

/ck save "discovered that ECS task role needs s3:GetObject on the artifacts bucket, 
not just the main media bucket"

Next session, that's in context from the start.

Cross-agent compatibility

common-knowledge files are plain Markdown. Any agent that can read text can consume them. I've used the same knowledge store with Claude Code, Cursor, and raw Claude API scripts. The format is intentionally simple: no agent-specific encoding, no binary blobs.

FAQ

What is common-knowledge? common-knowledge is a Git-backed knowledge store for AI coding agents. It lets agents save and load context — architecture decisions, gotchas, lessons — across sessions via a CLI interface.

Why use Git for agent memory? Git provides version history, diffing, and conflict resolution for free. Markdown files are human-readable and searchable with standard tools. Together they make agent memory transparent and debuggable.

Does common-knowledge work with agents other than Claude Code? Yes — the files are plain Markdown. Any agent that can read text can load common-knowledge context. The CLI is agent-agnostic.

Is common-knowledge open source? Yes — available at shihabshahrier/common-knowledge under MIT license.

How is this different from Claude's built-in memory? Claude's built-in memory is opaque (you can't inspect or edit it), model-specific (doesn't work with other agents), and doesn't support project organization. common-knowledge is transparent, version-controlled, cross-agent, and organized by project.

Written by Shihab Shahriar Antor — AI Engineer & Founder of Shahriar Labs. See also: Building Context-Heavy: Knowledge-Graph API for AI Agents · My AI Agent Skills Stack.