Metadata-Version: 2.4
Name: keep-memory
Version: 0.2.0
Summary: The engineering wiki for AI agents
Author: Eliasz Kowalski
License: Apache-2.0
Project-URL: Repository, https://github.com/EliaszDev/keep-memory
Project-URL: Homepage, https://github.com/EliaszDev/keep-memory
Project-URL: Issues, https://github.com/EliaszDev/keep-memory/issues
Project-URL: Changelog, https://github.com/EliaszDev/keep-memory/releases
Keywords: ai-agents,decisions,knowledge-base,mcp,okf,audit-trail
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: gitpython>=3.1.40
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=2.3.0; extra == "mcp"
Dynamic: license-file

# 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

```bash
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

```yaml
---
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

```python
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.

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

## License

Apache License 2.0
