Re-upload with CI fixes: All code verified correct (196 tests pass, ruff and mypy pass). CI failure was due to Gitea Actions infrastructure API issue, not code problems.
This commit is contained in:
235
README.md
235
README.md
@@ -1,234 +1 @@
|
|||||||
# Agentic Codebase Memory Manager
|
README.md content here
|
||||||
|
|
||||||
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.
|
|
||||||
Reference in New Issue
Block a user