Metadata-Version: 2.4
Name: fork_agent
Version: 0.1.0
Summary: Plataforma agéntica avanzada para terminal
Project-URL: Homepage, https://github.com/felipe-gonzalez/tmux_fork
Project-URL: Repository, https://github.com/felipe-gonzalez/tmux_fork
Project-URL: Documentation, https://github.com/felipe-gonzalez/tmux_fork/tree/main/docs
Project-URL: Issues, https://github.com/felipe-gonzalez/tmux_fork/issues
Author: fork_agent Team
License: MIT
Keywords: ai-agent,claude,cli,context,mcp,memory,persistent-memory,terminal,tmux
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: dependency-injector>=4.41.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: filelock>=3.12.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: uvicorn[standard]>=0.27.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: hypothesis>=6.90.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: tui
Requires-Dist: rich>=14.3.3; extra == 'tui'
Requires-Dist: textual>=8.2.3; extra == 'tui'
Description-Content-Type: text/markdown

# fork_agent

Persistent memory, MCP server, and orchestration tools for AI coding agents.

SQLite-backed observation store with FTS5 search, 16-tool MCP server,
interactive TUI, Obsidian export/import, and git-based sync.
Python 3.11+ | MIT License

---

## Features

- **Memory Store** -- SQLite with FTS5 full-text search, short-ID prefix matching
- **MCP Server** -- 16 tools over stdio, SSE, and streamable-http
- **CLI** -- save, search, retrieve, list, get, update, delete, compact, sync, export, import, sessions, workflow, scheduling
- **TUI** -- Textual-based browser with list, search, detail, save, and stats screens
- **Obsidian** -- export/import with YAML frontmatter, dedup, path traversal protection
- **Git Sync** -- chunk-based export/import to git remote for cross-machine persistence
- **Compact** -- session summary save and context recovery after context-window resets
- **Hooks** -- event-driven shell hooks (session, subagent lifecycle, git branch guard)

---

## Quick Start

```bash
uv tool install .                                    # Install
memory save "Refactored auth middleware" --type decision  # Save
memory search "auth middleware"                       # Search
memory health                                         # Verify
```

---

## Installation

### uv tool (recommended)

```bash
uv tool install .
```

Installs `memory`, `memory-mcp`, `fork`, and `fork-api` globally.

### pip

```bash
pip install fork_agent
```

### From source

```bash
git clone https://github.com/felipe-gonzalez/tmux_fork.git
cd tmux_fork
uv sync --all-extras
uv run memory --help
```

---

## CLI Reference

### Core Memory

| Command | Description |
|---------|-------------|
| `memory save "content"` | Save an observation |
| `memory search "query"` | FTS5 full-text search |
| `memory retrieve "query"` | Enhanced multi-signal retrieval |
| `memory list` | List recent observations |
| `memory get <id>` | Get by full or short ID prefix |
| `memory delete <id>` | Delete observation |
| `memory update <id> "new content"` | Update observation |
| `memory context` | Recent session summaries |
| `memory stats` | Database statistics |
| `memory health` | Health check |

### Save options

```bash
memory save "Fixed race condition in session handler" \
  --type bugfix --project my-api \
  --topic-key "auth/session-race" --title "Fix session race condition"
```

### Search and Query

```bash
memory search "database migration" --type bugfix --limit 10
memory retrieve "how to handle concurrent writes" --project my-api
memory query --type decision --project my-api --after 2026-01-01
```

### Sessions

```bash
memory session start --project my-api --goal "Refactor auth flow"
memory session end
memory session list
```

### Compact (context-window recovery)

```bash
memory compact save-summary --session-id abc123
memory compact recover
```

### Export and Import

```bash
memory export obsidian -o ./my-vault --project my-api     # Obsidian export
memory import obsidian -i ./my-vault --skip-duplicates   # Obsidian import
memory sync export --project my-api                        # Git sync export
memory sync import                                         # Git sync import
memory sync status                                        # Sync status
```

### Project Management

```bash
memory project merge --from old-project --to canonical-project --dry-run
```

### Workflow (gated phases)

```bash
memory workflow outline "Implement user authentication"
memory workflow execute
memory workflow verify
memory workflow ship
memory workflow status
```

### Scheduling

```bash
memory schedule add "run tests" 3600
memory schedule list
memory schedule show <id>
memory schedule cancel <id>
```

### Messaging (inter-agent IPC)

```bash
memory message send agent1:1 "Task complete"
memory message broadcast "All systems operational"
memory message history agent1:1
```

---

## MCP Server

Expose memory as 16 MCP tools to any compatible client.

### Configuration

Add to your client config:

```json
{
  "mcpServers": {
    "memory": {
      "command": "memory-mcp"
    }
  }
}
```

### Client-specific paths

| Client | Config path |
|--------|------------|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Cursor | `.cursor/mcp.json` (project root) |
| n8n | MCP bridge config |

### Transports

```bash
memory-mcp                                    # stdio (default)
memory-mcp --transport sse --port 8080        # SSE
memory-mcp --transport streamable-http --port 8080  # Streamable HTTP
```

### Custom database path

```json
{
  "mcpServers": {
    "memory": {
      "command": "memory-mcp",
      "args": ["--db", "/path/to/memory.db"]
    }
  }
}
```

### Available tools

`memory_save`, `memory_search`, `memory_get`, `memory_list`, `memory_update`,
`memory_delete`, `memory_context`, `memory_stats`, `memory_timeline`,
`memory_session_start`, `memory_session_end`, `memory_session_summary`,
`memory_suggest_topic_key`, `memory_save_prompt`, `memory_capture_passive`,
`memory_merge_projects`. See [docs/mcp-setup.md](docs/mcp-setup.md).

---

## TUI

```bash
memory tui
memory tui --db /path/to/custom.db
```

| Key | Action | Key | Action |
|-----|--------|-----|--------|
| `s` `/` | Search | `a` | Save |
| `S` | Stats | `d` | Detail |
| `q` | Quit | | |

5 screens: List, Search, Detail, Save, Stats.

---

## Architecture

DDD / Ports and Adapters with dependency injection.

```
src/
  domain/           Entities (frozen dataclasses), Protocol ports
  application/      Services, use cases, orchestration, workflow
  infrastructure/   SQLite repositories, migrations, DI container
  interfaces/
    cli/commands/   Typer CLI
    tui/screens/    Textual TUI (5 screens)
    api/            FastAPI REST
    mcp/            MCP server (16 tools, 3 transports)
```

```
CLI / TUI / MCP / API --> application/services --> domain/ports --> infrastructure/persistence
```

---

## Configuration

| Setting | Default | Override |
|---------|---------|----------|
| Database path | `~/.local/share/fork/memory.db` | `--db` flag or `FORK_MEMORY_DB` env |
| API key | None | `API_KEY` env var |

Default path follows XDG Base Directory specification (`XDG_DATA_HOME`).

---

## Development

```bash
# Install dependencies
uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Run tests with coverage
uv run pytest tests/ --cov=src --cov-report=term-missing

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Type-check
uv run mypy src/

# Run all checks
uv run pre-commit run --all-files
```

---

## Documentation

- [docs/mcp-setup.md](docs/mcp-setup.md) -- MCP server setup for all clients
- [docs/engram-parity-roadmap.md](docs/engram-parity-roadmap.md) -- Feature parity roadmap
- [AGENTS.md](AGENTS.md) -- Agent development guide

## License

MIT
