Initial upload: Agentic Codebase Memory Manager v0.1.0

2026-03-22 16:00:46 +00:00
parent 6da2ac30ee
commit 050660e178
1 changed files with 233 additions and 2 deletions
--- 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.
+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.