keep-memory

The engineering wiki for AI agents

Track architecture decisions, observations, and knowledge as git-native markdown files with validation, knowledge graphs, and agent session memory.

Features

• Typed Concepts — Decisions, Observations, APIs, Tables, Metrics, Projects, Sessions, Plans, Snapshots
• Knowledge Graphs — Automatic link extraction, traversal, backlinks, and networkx export
• Agent Memory — Session tracking, plan execution with step completion, state snapshots
• Git-Native — Auto-commit on agent actions, revert to any state, full history
• Validation — 3-level validation (bundle integrity, concept quality, cross-concept consistency)
• Search — Full-text search with inverted index and optional fuzzy matching
• MCP-Ready — Model Context Protocol server placeholder for AI tool integration

Quick Start

pip install -e .

# Initialize a knowledge bundle in your project
keep init

# Create a decision
keep create decision "Use PostgreSQL" --tags database,backend

# Search your knowledge base
keep search "postgresql"

# Validate for inconsistencies
keep validate

# View knowledge graph
keep graph

# Session tracking
keep session start
keep plan create "Refactor auth" --steps "extract module,write tests,update docs"
keep plan step "plans/refactor-auth_2024-01-15" 0 --result "module extracted"
keep snapshot --note "mid-refactor checkpoint"

Concept Format

---
id: use-postgresql
type: Decision
status: Active
tags: [database, backend]
author: eliasz
rationale: "Need relational database for structured data"
consequences:
  - "ACID transactions available"
  - "Requires connection pooling"
supersededBy: null
timestamp: 2024-07-15T10:30:00Z
---

# Body: Markdown content

Python API

from keep_memory import AgentMemory, GraphExtractor, MemoryMixin

# Agent memory with sessions, plans, and snapshots
memory = AgentMemory("./.keep-memory", agent_id="my-agent")
memory.start_session("session-1")
memory.record_decision("Use Redis", rationale="Cache layer needed")
memory.create_plan("Deploy v2", ["build", "test", "deploy"])
memory.snapshot(note="pre-deploy")

# Knowledge graph
from keep_memory import OKFBundle, GraphExtractor
bundle = OKFBundle.load()
graph = GraphExtractor(bundle)
edges = graph.get_edges()
tree = graph.traverse("architecture/overview", max_depth=2)

Development

Prerequisites: Python 3.10+ and git.

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest

License

Apache License 2.0