Recollect

Recollect gives your coding agents a shared Brain and the right tools to act. Connect Codex, Claude Code and OpenCode to one self-hosted service. Carry repository knowledge, decisions, runbooks and session memory across agents and repositories, so the next session can pick up where the last left off.

Bring memory and execution into one workflow: retrieve context with supporting evidence, authorize the tools an agent can use, and route approved MCP calls through the Recollect service or a paired private runner. Reach an internal filesystem or service from another machine while keeping execution inside your network.

Long-term memory, knowledge graphs, hybrid search and a Model Context Protocol (MCP) coordinator work together around the same Brain. Memories retain links to their sources, repository revisions and environments. Your coding agent stays in its familiar host; Recollect provides the shared knowledge, access rules and tool coordination. Inspect it all in the desktop web UI.

Early project: intended for individuals and trusted internal teams. The desktop redesign and private-runner workflow have local acceptance evidence. Remaining work and limits include further native-host direct-MCP acceptance and memory evaluation.

Product illustrations use example data and show the main workflows.

Why Recollect

A shared Brain, governed tools and private execution in one self-hosted service.

• Keep engineering context across agents and sessions. Capture supported sessions automatically, recall relevant knowledge with citations, and reuse decisions and fixes across repositories. Memory stays connected to its evidence and correction history.
• Give agents the right tools for each environment. Organize MCP connections into tool groups with independent Use, Manage and Share permissions. A person can read a Brain without permission to run its tools; environment scope keeps tool availability tied to the selected work context.
• Reach private tools from wherever you work. A paired runner connects outbound to Recollect and executes approved calls inside your network. The caller and runner can be different people or devices, and each connection has an explicit execution location.
• Keep control of your data and infrastructure. Self-host the service, choose capture, retention and AI-processing policies, and inspect knowledge, connections, permissions and tool-call outcomes in one UI. Model calls follow your configured provider policy.

When to use Recollect

• Continue work across sessions. Keep decisions, investigations, fixes and handovers available to the next coding agent.
• Understand a workspace across repositories. Connect code and configuration relationships with documentation, revision history and environment knowledge.
• Share context with a team. Organize knowledge in access-controlled Brains and give agents separately authorized tools for the work they need to do.

Run locally

Install Docker with Compose and Python 3.11+, then run:

git clone https://github.com/MikeK184/Recollect.git
cd Recollect
./scripts/stack.sh up --build

Open http://127.0.0.1:8787. The first run generates login credentials in the ignored .env file: use RECOLLECT_OWNER_USERNAME and RECOLLECT_OWNER_PASSWORD. The script builds the application and starts the complete recollect Compose group: PostgreSQL, Neo4j, UI/API and worker, with a one-shot migration first.

./scripts/stack.sh stop         # Stop everything; keep all data
./scripts/stack.sh up           # Start again
./scripts/stack.sh status       # Show service state
./scripts/stack.sh logs         # Follow API and worker logs
./scripts/stack.sh up --build   # Rebuild after code or UI changes

The root compose.yaml also supports standard docker compose commands. Use ./scripts/docker.sh compose if your Docker installation needs the repository's CLI wrapper. stop keeps containers and data; down removes the containers/network and keeps data. Do not add --volumes when retaining data.

For native development, stop the Compose stack, install Rust/Cargo and Node.js/npm, then run ./scripts/dev.sh. It runs only the databases in Docker and starts the API and worker in the terminal. Stop it with Ctrl+C before returning to Compose.

Learning and semantic search require an OPENAI_API_KEY in .env and an enabled Brain model policy. Model requests are billed by the provider. Browser-created Brains include the managed autonomous preset. Existing Brains keep their policy until Enable autonomous memory is selected; API creation defaults remain disabled unless managed setup is requested.

For Docker installation and shared HTTPS access, see the installation guide.

Connect your coding agent

Open Agents → Connect agent for Codex, Claude Code or OpenCode. Install the packaged plugin, connect once to your Brain, then start your coding host normally. The plugin bundles automatic capture, cited memory recall, local checkout discovery and repository publication. Independent local/private tool execution is optional through --with-runner. Advanced direct HTTP MCP remains available. Public marketplace distribution and native MCP OAuth login are not available yet.

Start here	Guide
Connect Codex, Claude Code or OpenCode to a Brain	Agent memory and MCP setup
Capture supported sessions and tool observations	Automatic session capture
Work across repositories, areas and environments	Workspace scope
Configure managed tools, credentials and private runners	MCP catalogue and runtime

The connection guide covers host configuration and a real tool-call check. Session capture depends on the supported host's hooks and your Brain's policies. Direct MCP uses a host configuration and access token; it does not install the plugin's automatic session-capture hooks.

For reproducible quality evidence, see the public retrieval benchmark and its measured results and limits.

Environments and tool access

Set up a connection once, include it in a tool group, and grant people or groups Use. Choose an environment when the tools should be available only for that work context. Execution placement controls which executor makes the MCP call.

Setting	Responsibility	Example
Connection scope	Where the MCP connection is eligible within its Brain	Brain-wide, or only Development
Tool group	Which connections a caller can use, with optional environment scope	Research tools contains Exa and requires Development
Use / Manage / Share	Independent permissions to run tools, edit a group, or grant access	A reader can Use without Manage or Share
Runs on	Which executor dispatches the approved MCP call	Recollect service, the caller's device, or a named private runner

The agent requests tools through Recollect. For centrally placed HTTP connections such as Exa, Recollect checks access and makes the MCP request to the remote service. The environment limits availability; it does not host the MCP server.

A Brain-wide connection can belong to an environment-specific tool group. That group limits its use to the selected environment; it does not move the MCP server. An environment-bound connection can only belong to a group in that same environment. A group cannot widen a connection's scope.

Without an enabled matching tool group and an explicit Use grant, the agent cannot execute that connection's tools. Brain administrators inherit Manage and Share, not Use. Grants are additive: another eligible group can still grant access. See the catalogue guide for setup.

Private runners

A private runner is an optional executor on a paired device inside your network. Use it for a filesystem MCP, internal service or another approved tool that the Recollect service cannot reach directly.

The runner initiates an outbound connection to your Recollect endpoint, claims its addressed work and returns the result. It needs access to Recollect and the MCP server; it does not need a public inbound port. Your coding agent can be on another machine and use either the plugin or direct MCP.

In Connections → Private Runners, add a paired device, copy its setup command and start the runner there. Assign a connection to that runner, then include it in a tool group with the caller's Use grant. The runner card shows its device, assigned MCP connections, approved tools and linked tool groups. A connection badge describes placement; the runner's live status describes connectivity.

Registering a runner does not install an MCP server or grant tool access. Executable commands, arguments and tool schemas come from approved definitions; an agent cannot turn the runner into an arbitrary shell. The plugin's automatic memory integration and optional execution runner have separate responsibilities.

See the private-runner setup guide and the Ubuntu filesystem proof. That local proof covers a real MCP caller, permitted reads, access denials and offline recovery; it does not claim a fresh LLM host session or production deployment.

What it does

Capability	What you get
Persistent agent memory	Decisions, claims, procedures and handovers that can be reused across sessions, with supporting evidence and correction history.
Brains and collections	Personal or shared knowledge spaces with access controls; collections group sources, while areas and environments provide overlapping views.
Hybrid retrieval	Exact, keyword, semantic and graph search with source references, scope and revision filters. Investigation and strict recall expose different trust requirements.
Knowledge and code graphs	Explore source-derived code/configuration relationships and knowledge links, with supported cross-repository paths and queued graph analytics.
Automatic learning	Capture, learn, revise and retire memories under standing policies. Manual review, corrections, withdrawal and erasure remain available.
MCP coordination	Connect agents to approved tools locally, centrally or through private runners. Tool execution has its own grants; Vault is an optional credential source.
Desktop web UI	Browse sources and memory, inspect graphs and processing, and see managed tool calls alongside their recorded outcomes.

How the pieces fit together

A Brain holds the knowledge and access rules for a person, team or project. Collections, repository snapshots and permitted session captures provide evidence. Memory processing derives claims and relationships; hybrid retrieval selects relevant context for the coding agent or UI, retaining links to that evidence.

PostgreSQL owns canonical records and policy state, pgvector supports semantic retrieval, and Neo4j/GDS supports graph traversal and analytics. Rust powers the API, workers and bundled plugin runtime; React provides the desktop UI. The same stack runs locally or on a private server.

Recollect owns its Rust core. Cognee and other memory systems inform the design; Cognee is not a required runtime.

Documentation

Browse the searchable documentation website or use the canonical repository guides below.

I want to…	Start here
Run locally or set up shared HTTPS access	Installation
Develop the backend or UI	Local development
Learn where features live in the desktop UI	Desktop guide
Configure learning and model access	Provider and learning policies
Operate memory, graphs, MCP and recovery	Operation guides
Understand the product and architecture	Vision and technology stack
See current work and remaining acceptance	Roadmap

Project status

The first planned product scope is implemented and locally tested. The desktop redesign, compact tool access and private-runner relationship cards have local acceptance evidence; mobile views are deferred. The active execution index tracks remaining direct-MCP native-host acceptance and the blocked LongMemEval evaluation. The evaluation report records measured results, failures and limits. Local validation is not a production capacity or deployment guarantee.

Contributing

Issues and focused pull requests are welcome. Include relevant tests for behavior changes and run ./scripts/validate.sh for the documentation checks. See AGENTS.md for repository conventions and the development guide for product tests.

License

Licensed under Apache-2.0.