A centralized memory store for AI coding agents working on the same project. Features a FastAPI JSON API, CLI interface with git-like commands, and a TUI dashboard for visualizing codebase decisions, implemented features, refactoring history, and architectural choices.

Overview

Memory Manager allows AI agents to store and retrieve context about a codebase, avoiding duplicate work and enabling better coordination. It provides:

Persistent Memory: Store decisions, features, refactorings, and architectural choices
Git-like Versioning: Commit snapshots of memory state, view history, diff between commits
Full-text Search: Search across all entries with SQLite FTS5
REST API: JSON API for integration with other tools
Interactive TUI: Terminal dashboard for visual exploration
CLI Interface: Git-like commands for scripting and automation

Features

✨ Centralized memory store for AI agents
🚀 CLI and JSON API for reading/writing memory entries
🔧 TUI dashboard to visualize project memory
📝 Git-like interface for memory commits
🔍 Search and query memory by context
🔗 Integration hooks for popular AI coding tools

Installation

pip install memory-manager

Or install from source:

git clone <repository-url>
cd agentic-codebase-memory-manager
pip install -e .

Quick Start

CLI

# Add a memory entry
memory add --title "Use SQLite" --content "We decided to use SQLite for local storage" --category decision --tags storage,database

# List all entries
memory list

# Search entries
memory search "SQLite"

# Commit current state
memory commit --message "Initial project decisions"

# View commit history
memory log

# Start API server
memory serve

# Launch TUI dashboard
memory tui

API

# Start the server
memory serve

# Or use the API directly
curl http://localhost:8080/api/memory
curl http://localhost:8080/api/memory -X POST -H "Content-Type: application/json" -d '{"title": "Use Redis", "content": "Caching layer", "category": "architecture", "tags": ["cache"]}'
curl http://localhost:8080/api/memory/search?q=cache

CLI Commands

Command	Description
`memory add`	Add a new memory entry
`memory list`	List memory entries
`memory search`	Search memory entries
`memory get`	Get a specific entry
`memory update`	Update an entry
`memory delete`	Delete an entry
`memory commit`	Create a commit snapshot
`memory log`	Show commit history
`memory diff`	Show diff between commits
`memory serve`	Start the API server
`memory tui`	Launch the TUI dashboard

REST API

Endpoints

Method	Endpoint	Description
GET	`/api/memory`	List all entries
POST	`/api/memory`	Create new entry
GET	`/api/memory/{id}`	Get entry by ID
PUT	`/api/memory/{id}`	Update entry
DELETE	`/api/memory/{id}`	Delete entry
GET	`/api/memory/search?q=`	Search entries
POST	`/api/memory/commit`	Create commit
GET	`/api/memory/log`	Get commit log
GET	`/api/memory/diff/{h1}/{h2}`	Diff two commits
GET	`/api/memory/stats`	Get statistics

Request/Response Examples

// POST /api/memory
{
  "title": "Use PostgreSQL",
  "content": "We decided to use PostgreSQL for the main database due to its reliability and feature set.",
  "category": "decision",
  "tags": ["database", "postgresql", "storage"]
}

// Response
{
  "id": 1,
  "title": "Use PostgreSQL",
  "content": "We decided to use PostgreSQL...",
  "category": "decision",
  "tags": ["database", "postgresql", "storage"],
  "agent_id": "agent-123",
  "project_path": "/path/to/project",
  "created_at": "2024-01-15T10:30:00",
  "updated_at": "2024-01-15T10:30:00"
}

API documentation available at http://localhost:8080/docs (Swagger UI).

TUI Dashboard

Launch with memory tui. Keybindings:

d - Dashboard screen
l - Memory list screen
c - Commit history screen
s - Search screen
q - Quit

Configuration

Environment Variables

Variable	Default	Description
`MEMORY_DB_PATH`	`.memory/codebase_memory.db`	SQLite database path
`MEMORY_API_HOST`	`127.0.0.1`	API server host
`MEMORY_API_PORT`	`8080`	API server port
`MEMORY_PROJECT_PATH`	`.`	Project root path
`AGENT_ID`	`unknown`	Agent identifier

Project Config

Optional .memory/config.toml in project root:

[project]
name = "my-project"
db_path = ".memory/codebase_memory.db"

[api]
host = "127.0.0.1"
port = 8080

Architecture

src/memory_manager/
├── api/          # FastAPI REST API
├── cli/          # Click CLI commands
├── core/         # Business logic services
├── db/           # SQLAlchemy models and repository
└── tui/          # Textual TUI application

Key Components

MemoryService: CRUD operations for memory entries
SearchService: Full-text search with FTS5
CommitService: Git-like versioning with snapshots and diffs
MemoryRepository: Async SQLAlchemy operations with aiosqlite

Integration with AI Tools

Cursor

Add to your Cursor project settings or .cursor/rules:

Use the Memory Manager API at http://localhost:8080 to:
1. Check existing decisions before making new ones
2. Record significant decisions with: POST /api/memory
3. Search past decisions with: GET /api/memory/search?q=

GitHub Copilot

Create a Copilot extension that calls the Memory Manager API to contextually retrieve relevant past decisions when working on similar code.

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit
memory commit --message "Auto-save before commit" 2>/dev/null || true

Contributing

Contributions welcome! Please read the contributing guidelines and submit pull requests.

License

MIT License - see LICENSE file for details.

README.md

Agentic Codebase Memory Manager