Metadata-Version: 2.4
Name: forgemem
Version: 0.1.1
Summary: Persistent memory for AI agents — cross-session context that actually sticks
Author: Forgemem Contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/kalinovdameus/forgemem
Project-URL: Documentation, https://github.com/kalinovdameus/forgemem#readme
Project-URL: Bug Tracker, https://github.com/intelogroup/forgemem/issues
Keywords: mcp,ai,memory,claude,llm,agents,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.28.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: flask>=2.3.0
Requires-Dist: requests>=2.31.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Dynamic: license-file

# Forgemem

**Long-term memory and knowledge base built from your real activity as a developer.**

Forgemem mines your git history, session traces, and project notes to extract what actually happened — failures, successes, plans, and hard-won lessons. It stores them in a local SQLite database so that any agent you work with can learn from your past before wasting tokens walking down paths you've already hit dead ends on.

## The Problem It Solves

Every new agent session starts blind. It doesn't know that you already tried the Zod 4 schema approach and it broke. It doesn't know that wildcard CORS killed auth in production. It doesn't know that the cleanup phase always needs to come after the dev phase, not during.

Without Forgemem, agents repeat your mistakes. With it, they skip to what works.

## How It Works

1. **Daily scan** — runs against your git repos and memory files, extracts failure/success/plan traces via Claude, and saves them with an impact score
2. **SQLite DB** — stores all traces and distilled principles locally at `~/.forgemem/forgemem_memory.db`
3. **MCP server** — exposes the DB to agents via the Model Context Protocol so they can query it before starting any task

## MCP Access

### Claude Code (stdio — already configured)
Any Claude Code session on this machine has Forgemem registered globally in `~/.claude/settings.json`. No setup needed — just call `retrieve_memories` before starting work.

### Other agents (Gemini CLI, OpenCode, Copilot) — HTTP/SSE
Start the HTTP server:
```bash
cd ~/Developer/Forgemem
.venv/bin/python3 mcp_server.py --http
# → http://127.0.0.1:7474/sse
```
Then point your agent's MCP config at `http://127.0.0.1:7474/sse`.

## Tools Exposed

| Tool | Purpose |
|------|---------|
| `retrieve_memories` | Search principles and traces by keyword before starting a task |
| `save_trace` | Save a failure, success, plan, or note during/after a session |
| `forgemem_stats` | Summary of DB contents + agent connection history |

## Key Commands

```bash
# Run the daily knowledge mining scan
.venv/bin/python3 daily_scan.py

# Query from CLI
.venv/bin/python3 forgemem.py retrieve "auth debugging"

# Check DB stats + who connected
.venv/bin/python3 forgemem.py stats
```

## The Goal

Agents should always call `retrieve_memories` at the start of any task. That one call surfaces the top failures and principles from your history that match what they're about to do — so they don't burn tokens re-learning what you already know.

## Licensing & Commercial Use

Forgemem is **Apache-2.0** for community use. Hosted service offerings (if any) are covered by separate commercial terms.

- **Community**: Apache-2.0 (permissive, local-first, commercial-friendly)
- **Enterprise**: hosted terms with optional SLA, SSO/SAML, audit logs, priority support, and private hosting options
- **Donations**: GitHub Sponsors (coming soon)

**Contributing**: All contributors must sign the [CLA](CLA.md) by adding their name to [CONTRIBUTORS.md](CONTRIBUTORS.md) in their first PR.
