MemForge

Self-evolving, evidence-based agent memory layer for Codex, Claude Code, and development teams.

Status: alpha. APIs, storage formats, and integration packaging may change while the project settles.

MemForge is a self-evolving memory layer for AI coding agents. It turns scattered team context into structured, source-traced memories that agents can search, verify, and reuse.

It connects to the systems teams already use, such as Confluence, Jira, GitHub Pages, Microsoft Teams, and long coding-agent sessions. On each sync, MemForge extracts durable facts, decisions, procedures, and conventions while preserving source evidence and history.

AI coding assistants often start each session blind to institutional context. MemForge bridges that gap through MCP-enabled agent plugins, an admin API, and integrations, with review flows for superseded facts and contradictions.

What It Does

• Ingests source context from genes such as wiki pages, issue trackers, GitHub Pages, Teams exports, and generated agent-session packages.
• Extracts durable facts, decisions, procedures, and conventions with quality gates before persistence.
• Stores memory, provenance, review state, full-text search, and vector search in a local or self-hosted service.
• Ships thin MCP proxies for Codex, Claude Code, and other clients so agents can search, inspect provenance, and cache source artifacts locally while the service owns memory logic.
• Provides a React admin UI for source management, review queues, memory detail, entity browsing, and runtime settings.

Built-in genes today: confluence, jira, github_pages, teams, agent_session, and local_markdown.

Integrations

MemForge connects the systems where team context is created with the agents that need it during real work. Instead of rediscovering context every session, source systems sync into evidence-backed memories that agents can retrieve when they matter.

Agent Integrations

Once installed, each plugin gives your agent a two-way memory loop out of the box: it can pull source-traced context while you code, and MemForge can turn useful work from the session into new memories afterward.

Supported today: Codex    Claude Code

Memory Sources

Source	What MemForge captures
Confluence	Pages, runbooks, architecture decisions, and exported PDFs. Reprocessed when source content changes.
Jira	Issues, delivery outcomes, and conventions that outlive a ticket.
GitHub Pages	Published docs and design references from static project sites.
Teams	Decisions, significant discussions, and follow-ups from team conversations.
Local Repository	Any local folder or repo synced via the CLI (Obsidian vaults, plain folders). Markdown, text, JSON, and HTML files become source-traced memories, on demand or on a schedule. See docs/local-repo-sync.md.

More source connectors are in development, including Slack, Outlook, and custom team systems. Cursor and other agent runtimes can follow the same integration pattern. Built-in support today is the set listed above.

Architecture

flowchart LR
  Agent["Agent client\nCodex / Claude Code"]
  Adapter["Thin adapter\nhooks + local MCP proxy"]
  API["MemForge API"]
  Pipeline["Extraction pipeline\nquality + reconciliation"]
  Store["SQLite + FTS\nChroma vectors"]
  UI["Admin UI"]

  Agent --> Adapter
  Adapter -->|"redacted windows"| API
  API --> Pipeline
  Pipeline --> Store
  UI --> API
  Agent -->|"MCP tool calls"| Adapter
  Adapter -->|"search / get_memory / artifacts"| API

Client adapters collect bounded, redacted evidence windows and upload them to POST /api/agent-sessions/windows. The service canonicalizes the window, generates the package, and queues the source sync. This keeps agent clients portable across local and future hosted deployments.

For MCP, Codex and Claude Code talk to a plugin-local proxy over stdio. That proxy calls the self-hosted or hosted MemForge API over HTTP(S), so search and provenance logic stay service-owned while get_resource(mode="file") can still return a real path on the agent machine.

Quick Start

Requirements:

• Docker with a current Compose v2

git clone https://github.com/shno-labs/mem-forge.git
cd mem-forge

docker compose up --build

Open http://localhost:5174. The compose stack starts the MemForge API, serves the admin UI, and keeps local data in the memforge-data Docker volume. Copy .env.example to .env when you want to set model keys or local overrides. The OSS public beta has no built-in request authentication, so Docker publishes both the UI and API on host loopback only. Browser, CLI, local-agent daemon, and host-side Codex or Claude clients can connect from the same machine; other LAN devices cannot. A client in another container has its own localhost and needs an explicitly configured host/container route rather than a wider host binding. If Docker Hub is slow or blocked in your network, set MEMFORGE_DOCKERHUB_PREFIX in .env to a mirror prefix such as docker.m.daocloud.io/library/, then rerun the same command. For restricted or slow registry networks, use the bundled mirror profile:

docker compose --env-file .env.mirrors.example up --build

The API image uses WeasyPrint for Confluence PDF export and does not require a browser runtime. When an agent needs backing source content from a Docker-hosted service, it should call get-memory for provenance and then read the returned content_url or pdf_url through MemForge's artifact endpoints instead of depending on service-local filesystem paths.

For detailed setup, configuration, and first-source examples, see docs/quickstart.md.

The complete docs map is in docs/README.md.

Install the host-side CLI in an isolated environment when you want to query a running MemForge service or run local-source adapters from this machine:

pipx install memforge-ai
memforge --help

memforge-ai is the Python distribution name; the installed command and import package remain memforge.

Configure the current target and install the local collection daemon as a login user service with one guided command:

# Guided setup; press Enter to use the local self-hosted target
memforge setup

# Or configure a hosted target; the token is prompted and saved in the OS keyring
memforge setup --api-url https://memory.example.com

With no active target, the guided command prompts for the API URL and offers the local self-hosted endpoint as its default. MemForge discovers the exact origin's edition, authentication requirement, API base, and health path from /.well-known/memforge; it does not infer service type from the hostname.

The setup command manages launchd on macOS and the systemd user manager on Linux. Use memforge daemon status, check, restart, logs, stop, start, and uninstall for subsequent operations; users do not need to write native service files or keep a terminal open. Status and check include the server-observed heartbeat, so users can prove connectivity before scheduling or triggering a source sync.

You can also exercise the same read path from the CLI:

memforge
memforge search "docker artifact provenance"
memforge get-memory mem-123
memforge get-resource /api/documents/doc-456/pdf --mode file

The CLI uses MEMFORGE_API_URL and optional MEMFORGE_API_TOKEN when set; otherwise it targets the local Admin API port from config. The bare interactive CLI requires Node.js on PATH; MemForge prepares the packaged Clack menu in a user cache on first use, so no manual cd cli && npm install step is required.

Plugin Installation

Installable plugin packages live under:

• integrations/codex/memforge-memory
• integrations/claude-code/memforge-memory

Add this repository as a marketplace and install the plugin (no checkout required; the marketplace is fetched directly from GitHub):

# Codex
codex plugin marketplace add shno-labs/mem-forge
codex plugin add memory@memforge

# Claude Code (run inside an active Claude Code session)
/plugin marketplace add shno-labs/mem-forge
/plugin install memory@memforge

For normal self-hosted use, the plugin talks to the running MemForge API at http://127.0.0.1:8765. Set MEMFORGE_API_URL and optional MEMFORGE_API_TOKEN only when pointing the plugin at another local or hosted service. The same /api/v1 contract is used by self-hosted and Cloud. MCP offers list_workspaces; every other tool accepts an optional workspace_id. Installable clients resolve a user-confirmed local project binding and send it as an explicit selector. Omission is safe only when exactly one accessible workspace remains. Self-hosted exposes the single readable workspace id local.

export MEMFORGE_API_URL=https://api.example.memforge
export MEMFORGE_API_TOKEN=...

After installing, talk to your agent like a teammate with project memory:

I'm about to change the agent-session capture flow.
Check MemForge for the decisions, conventions, and source evidence that matter.
If a memory points to a backing page or PDF, inspect it when the original context
could change your recommendation.

The plugin returns compact memory cards from search. Agents call get_memory for source provenance, then use its Document content_url/pdf_url or revision-pinned evidence_artifacts[].url links with get_resource when they need more than the memory card.

Both plugins follow the same MemForge boundary: the local agent gets useful memory in the moment, while the service owns extraction, provenance, and review. See docs/integrations/agent-clients.md for the client-side versus service-side design.

Project Layout

src/memforge/        Python service, CLI, pipeline, genes, plugin MCP proxy
admin-ui/               React admin console
integrations/           Codex and Claude Code plugin packages
docs/design/            Design notes for memory extraction and agent sessions
tests/                  Python tests

Development

Requirements:

• Python 3.12 or newer
• Node.js 20 or newer
• uv recommended for Python dependency management

Common commands:

uv sync --extra dev
cp .env.example .env
uv run memforge api

In another terminal:

cd admin-ui
npm ci
npm run dev

Before opening a pull request:

uv run ruff check src tests
uv run pytest -q

cd admin-ui
npm ci
npm run lint
npm test
npm run build

The same checks are wired in GitHub Actions. See CONTRIBUTING.md before opening a pull request.

Status

MemForge is alpha software. The local/self-hosted path is the primary target today. The agent-session boundary is designed so the same adapters can point at a hosted service later without teaching the service to read local transcript files.

License

Apache License 2.0. See LICENSE.