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 (mem-forge) 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.
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.

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

uv run memforge
uv run memforge search "docker artifact provenance"
uv run memforge get-memory mem-123
uv run 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. Hosted multi-workspace deployments also need MEMFORGE_WORKSPACE_ID
so MCP calls target the workspace-scoped API path. Self-hosted OSS does not
support workspace routing; remove MEMFORGE_WORKSPACE_ID from the client
environment or MemForge client configuration when switching from Cloud to a
local or other self-hosted origin.

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

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.