From 050660e178b314cf24f3a4bd8a184718d69267bc Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Sun, 22 Mar 2026 16:00:46 +0000 Subject: [PATCH] Initial upload: Agentic Codebase Memory Manager v0.1.0 --- README.md | 235 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 233 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 06705cb..24186a3 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,234 @@ -# agentic-codebase-memory-manager +# Agentic Codebase Memory Manager -A centralized memory store for AI coding agents. Provides a CLI tool, REST API, and TUI dashboard for maintaining shared context across multiple AI coding agents working on the same project. \ No newline at end of file +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