Metadata-Version: 2.5
Name: memforge-ai
Version: 0.1.57
Summary: Evidence-based agent memory layer for Codex, Claude Code, and development teams
Project-URL: Homepage, https://github.com/shno-labs/mem-forge
Project-URL: Repository, https://github.com/shno-labs/mem-forge
Project-URL: Issues, https://github.com/shno-labs/mem-forge/issues
Author: MemForge Contributors
License: Apache License
        Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
        "License" shall mean the terms and conditions for use, reproduction, and
        distribution as defined by Sections 1 through 9 of this document.
        
        "Licensor" shall mean the copyright owner or entity authorized by the
        copyright owner that is granting the License.
        
        "Legal Entity" shall mean the union of the acting entity and all other
        entities that control, are controlled by, or are under common control with that
        entity. For the purposes of this definition, "control" means (i) the power,
        direct or indirect, to cause the direction or management of such entity,
        whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or
        more of the outstanding shares, or (iii) beneficial ownership of such entity.
        
        "You" (or "Your") shall mean an individual or Legal Entity exercising
        permissions granted by this License.
        
        "Source" form shall mean the preferred form for making modifications, including
        but not limited to software source code, documentation source, and configuration
        files.
        
        "Object" form shall mean any form resulting from mechanical transformation or
        translation of a Source form, including but not limited to compiled object code,
        generated documentation, and conversions to other media types.
        
        "Work" shall mean the work of authorship, whether in Source or Object form,
        made available under the License, as indicated by a copyright notice that is
        included in or attached to the work.
        
        "Derivative Works" shall mean any work, whether in Source or Object form, that
        is based on (or derived from) the Work and for which the editorial revisions,
        annotations, elaborations, or other modifications represent, as a whole, an
        original work of authorship. For the purposes of this License, Derivative Works
        shall not include works that remain separable from, or merely link (or bind by
        name) to the interfaces of, the Work and Derivative Works thereof.
        
        "Contribution" shall mean any work of authorship, including the original
        version of the Work and any modifications or additions to that Work or
        Derivative Works thereof, that is intentionally submitted to Licensor for
        inclusion in the Work by the copyright owner or by an individual or Legal Entity
        authorized to submit on behalf of the copyright owner. For the purposes of this
        definition, "submitted" means any form of electronic, verbal, or written
        communication sent to the Licensor or its representatives, including but not
        limited to communication on electronic mailing lists, source code control
        systems, and issue tracking systems that are managed by, or on behalf of, the
        Licensor for the purpose of discussing and improving the Work, but excluding
        communication that is conspicuously marked or otherwise designated in writing by
        the copyright owner as "Not a Contribution."
        
        "Contributor" shall mean Licensor and any individual or Legal Entity on behalf
        of whom a Contribution has been received by Licensor and subsequently
        incorporated within the Work.
        
        2. Grant of Copyright License. Subject to the terms and conditions of this
        License, each Contributor hereby grants to You a perpetual, worldwide,
        non-exclusive, no-charge, royalty-free, irrevocable copyright license to
        reproduce, prepare Derivative Works of, publicly display, publicly perform,
        sublicense, and distribute the Work and such Derivative Works in Source or
        Object form.
        
        3. Grant of Patent License. Subject to the terms and conditions of this
        License, each Contributor hereby grants to You a perpetual, worldwide,
        non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have
        made, use, offer to sell, sell, import, and otherwise transfer the Work, where
        such license applies only to those patent claims licensable by such Contributor
        that are necessarily infringed by their Contribution alone or by combination of
        their Contribution with the Work to which such Contribution was submitted. If
        You institute patent litigation against any entity alleging that the Work or a
        Contribution incorporated within the Work constitutes direct or contributory
        patent infringement, then any patent licenses granted to You under this License
        for that Work shall terminate as of the date such litigation is filed.
        
        4. Redistribution. You may reproduce and distribute copies of the Work or
        Derivative Works thereof in any medium, with or without modifications, and in
        Source or Object form, provided that You meet the following conditions:
        
        (a) You must give any other recipients of the Work or Derivative Works a copy
        of this License; and
        
        (b) You must cause any modified files to carry prominent notices stating that
        You changed the files; and
        
        (c) You must retain, in the Source form of any Derivative Works that You
        distribute, all copyright, patent, trademark, and attribution notices from the
        Source form of the Work, excluding those notices that do not pertain to any part
        of the Derivative Works; and
        
        (d) If the Work includes a "NOTICE" text file as part of its distribution, then
        any Derivative Works that You distribute must include a readable copy of the
        attribution notices contained within such NOTICE file, excluding those notices
        that do not pertain to any part of the Derivative Works, in at least one of the
        following places: within a NOTICE text file distributed as part of the
        Derivative Works; within the Source form or documentation, if provided along
        with the Derivative Works; or within a display generated by the Derivative
        Works, if and wherever such third-party notices normally appear. The contents of
        the NOTICE file are for informational purposes only and do not modify the
        License. You may add Your own attribution notices within Derivative Works that
        You distribute, alongside or as an addendum to the NOTICE text from the Work,
        provided that such additional attribution notices cannot be construed as
        modifying the License.
        
        You may add Your own copyright statement to Your modifications and may provide
        additional or different license terms and conditions for use, reproduction, or
        distribution of Your modifications, or for any such Derivative Works as a
        whole, provided Your use, reproduction, and distribution of the Work otherwise
        complies with the conditions stated in this License.
        
        5. Submission of Contributions. Unless You explicitly state otherwise, any
        Contribution intentionally submitted for inclusion in the Work by You to the
        Licensor shall be under the terms and conditions of this License, without any
        additional terms or conditions. Notwithstanding the above, nothing herein shall
        supersede or modify the terms of any separate license agreement you may have
        executed with Licensor regarding such Contributions.
        
        6. Trademarks. This License does not grant permission to use the trade names,
        trademarks, service marks, or product names of the Licensor, except as required
        for reasonable and customary use in describing the origin of the Work and
        reproducing the content of the NOTICE file.
        
        7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
        writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR
        CONDITIONS OF ANY KIND, either express or implied, including, without
        limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
        MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely
        responsible for determining the appropriateness of using or redistributing the
        Work and assume any risks associated with Your exercise of permissions under
        this License.
        
        8. Limitation of Liability. In no event and under no legal theory, whether in
        tort (including negligence), contract, or otherwise, unless required by
        applicable law (such as deliberate and grossly negligent acts) or agreed to in
        writing, shall any Contributor be liable to You for damages, including any
        direct, indirect, special, incidental, or consequential damages of any character
        arising as a result of this License or out of the use or inability to use the
        Work, even if such Contributor has been advised of the possibility of such
        damages.
        
        9. Accepting Warranty or Additional Liability. While redistributing the Work or
        Derivative Works thereof, You may choose to offer, and charge a fee for,
        acceptance of support, warranty, indemnity, or other liability obligations
        and/or rights consistent with this License. However, in accepting such
        obligations, You may act only on Your own behalf and on Your sole
        responsibility, not on behalf of any other Contributor, and only if You agree to
        indemnify, defend, and hold each Contributor harmless for any liability incurred
        by, or claims asserted against, such Contributor by reason of your accepting any
        such warranty or additional liability.
        
        END OF TERMS AND CONDITIONS
        
        Copyright 2026 MemForge Contributors
License-File: LICENSE
Keywords: agent-memory,claude-code,codex,coding-agents,llm,mcp,mcp-server,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20
Requires-Dist: anthropic>=0.40
Requires-Dist: apscheduler>=3.10
Requires-Dist: bcrypt>=4.2
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: browser-cookie3>=0.20
Requires-Dist: chromadb>=0.5
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=42
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25.7
Requires-Dist: litellm>=1.74
Requires-Dist: markdownify>=0.13
Requires-Dist: pillow>=11.0
Requires-Dist: pip-system-certs>=5.3
Requires-Dist: playwright>=1.52
Requires-Dist: pydantic>=2.9
Requires-Dist: pyjwt>=2.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.9
Requires-Dist: tiktoken>=0.7
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: uvicorn>=0.34
Requires-Dist: weasyprint>=68.1
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: langfuse
Requires-Dist: langfuse<5,>=4.14; extra == 'langfuse'
Description-Content-Type: text/markdown

# MemForge

<p align="center">
  <img src=".github/assets/memforge-banner.png" alt="MemForge - Agent memory layer" width="100%">
</p>

<p align="center">
  <a href="https://github.com/shno-labs/mem-forge/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/shno-labs/mem-forge/actions/workflows/ci.yml/badge.svg"></a>
  <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-3776AB">
  <img alt="License Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue">
  <img alt="Status alpha" src="https://img.shields.io/badge/status-alpha-f59e0b">
  <img alt="Code style Ruff" src="https://img.shields.io/badge/code%20style-ruff-111827">
</p>

*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:** <img alt="Codex" src="https://api.iconify.design/simple-icons:openai.svg?color=%23000000" width="18"> **Codex** &nbsp;&nbsp; <img alt="Claude Code" src="https://api.iconify.design/simple-icons:claude.svg?color=%23D97757" width="18"> **Claude Code**

### Memory Sources

| Source | What MemForge captures |
| --- | --- |
| <img alt="Confluence" src="https://api.iconify.design/simple-icons:confluence.svg?color=%23172B4D" width="18"> **Confluence** | Pages, runbooks, architecture decisions, and exported PDFs. Reprocessed when source content changes. |
| <img alt="Jira" src="https://api.iconify.design/simple-icons:jira.svg?color=%230052CC" width="18"> **Jira** | Issues, delivery outcomes, and conventions that outlive a ticket. |
| <img alt="GitHub" src="https://api.iconify.design/simple-icons:github.svg?color=%23181717" width="18"> **GitHub Pages** | Published docs and design references from static project sites. |
| <img alt="Microsoft Teams" src="https://api.iconify.design/simple-icons:microsoftteams.svg?color=%236264A7" width="18"> **Teams** | Decisions, significant discussions, and follow-ups from team conversations. |
| <img alt="Local Repository" src="https://api.iconify.design/simple-icons:obsidian.svg?color=%237C3AED" width="18"> **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](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

```mermaid
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

```bash
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:

```bash
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](docs/quickstart.md).

The complete docs map is in [docs/README.md](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:

```bash
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:

```bash
# 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:

```bash
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/codex/memforge-memory)
- [integrations/claude-code/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):

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

```text
# 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`.

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

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

```text
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](docs/integrations/agent-clients.md) for
the client-side versus service-side design.

## Project Layout

```text
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:

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

In another terminal:

```bash
cd admin-ui
npm ci
npm run dev
```

Before opening a pull request:

```bash
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](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](LICENSE).
