Metadata-Version: 2.5
Name: agent-memory-brain
Version: 0.3.1
Summary: Brain: local long-term memory, agent messages and a localhost dashboard for coding agents (MCP server)
Author: Benjamin Breznik
License-Expression: LicenseRef-PolyForm-Small-Business-1.0.0
License-File: LICENSE
Keywords: ai-agents,claude-code,codex,mcp,memory
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: fastembed<0.10,>=0.9.1
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: mcp<2,>=1.9
Requires-Dist: uvicorn<1,>=0.30
Description-Content-Type: text/markdown

# Brain

Brain gives coding agents durable, local context: long-term project memory, agent-to-agent messages, and a localhost dashboard through an MCP server. It works with Claude Code and Codex, while keeping the Python import name and existing `devmem` command available for compatibility.

Windows, macOS, and Linux are supported. Windows is supported natively starting with this release.

## Install

Install Brain as a tool:

```sh
uv tool install agent-memory-brain
```

Or use pipx:

```sh
pipx install agent-memory-brain
```

If `brain` is not yet on your `PATH`, run `uv tool update-shell`, follow its shell instructions, and open a new terminal. Until then, use the absolute executable path from `uv tool dir --bin`.

## Connect an agent

Register the MCP server for Claude Code:

```sh
claude mcp add brain -s user -- brain mcp
```

If `brain` is not on `PATH`, replace it in that command with the absolute executable path from `uv tool dir --bin`.

For Codex, add this to `~/.codex/config.toml` (use the absolute path if needed). The MCP server's internal name remains `devmem` for compatibility:

```toml
[mcp_servers.devmem]
command = "brain"
args = ["mcp"]
```

To include a compact project briefing at the start of a Claude Code session, optionally configure a SessionStart hook that runs:

```sh
brain context --hook
```

## Dashboard

Start the local panel:

```sh
brain panel
```

Then open <http://127.0.0.1:8765>. The dashboard shows activity, projects, sessions, memories, messages, and optional integrations.

## Memory that stays useful

Use the MCP tools to save decisions, preferences, snippets, notes, and follow-ups. Search combines keywords with local semantic embeddings when enabled; `brain embed` backfills embeddings and `DEVMEM_EMBED=0` keeps operation keyword-only. The CLI also offers `brain search`, `brain context`, and `brain audit`.

Changes and deletions retain revision history (`memory_history` and `memory_restore`). Pin only the facts needed in every session, and use typed memory links rather than repeating related context. `brain maintain --dry-run` previews optional maintenance work before it changes anything.

## Privacy and network

All memory data stays in `~/.devmem/devmem.db`, and the panel binds only to localhost. Brain reads, but never modifies, logs in `~/.claude/projects` and `~/.codex/sessions`.

On first embedding use, FastEmbed may download its model into `~/.devmem/models`; set `DEVMEM_EMBED=0` to disable embeddings. The following features are off unless configured: the Azure DevOps panel (requires `~/.devmem/ado.json` and a user-created token file), git sync (a user-configured git remote), automatic maintenance (runs local `codex exec` or `claude -p`), and panel chat dispatch (runs local Claude or Codex CLIs).

## Guard limits

Command guard rules match literal command text, so dynamic forms such as `x=git; $x commit` or `eval` can bypass them. Put hard limits in OS permissions; path rules still inspect command tokens.

## Configuration

Configuration names deliberately remain compatible: environment variables continue to use the `DEVMEM_*` prefix and data/configuration paths remain under `~/.devmem/`. Common settings include `DEVMEM_DB`, `DEVMEM_EMBED`, `DEVMEM_MAX_CONTENT`, `DEVMEM_PANEL_PORT`, `DEVMEM_MAINTAIN`, and `DEVMEM_ADO_CONFIG`.

## License

Brain is free for individuals and small businesses under the PolyForm Small Business License 1.0.0. Larger companies can contact the author for a commercial license via the PyPI project page.

The paid Agensi skill pack teaches agents to use Brain well.
