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

```bash
pip install memory-manager
```

Or install from source:

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

## Quick Start

### CLI

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

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

```json
// 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"]
}
```

```json
// 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:

```toml
[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

```bash
#!/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.