agentic-codebase-memory-manager/README.md

Agentic Codebase Memory Manager

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

Categories

• decision - Architectural and design decisions
• feature - Implemented features
• refactoring - Refactoring history
• architecture - Architectural patterns and structures
• bug - Bug fixes and known issues
• note - General notes and observations

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.