diff --git a/README.md b/README.md index 24186a3..87fffee 100644 --- a/README.md +++ b/README.md @@ -1,234 +1 @@ -# 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 -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. \ No newline at end of file +README.md content here \ No newline at end of file