firm-memory

Eine Speicherschicht, die unseren KI-Codierungsagenten merken lässt, wie diese Firma Software baut, damit sie nicht bei jedem Aufruf dieselben Dinge neu lernen müssen.

CodeGraph beantwortet „Was macht der Code?" Firm Memory beantwortet „Warum bauen wir es so?"

CodeGraph bleibt für das aktuelle Verhalten des Codes maßgeblich. Memory hält kontextuelles Engineering-Wissen – und kann veralten. Deshalb gilt: Wenn Memory und aktueller Code sich widersprechen, gewinnt der Code.

Das Grundprinzip

  OpenCode        On-call        Future agent
      └───────────────┼───────────────┘
                      │  MCP
             ┌────────▼─────────┐
             │  Firm Memory MCP │   thin transport adapter
             └────────┬─────────┘
                      │
             ┌────────▼─────────┐
             │   Firm Memory    │   taxonomy · scope · provenance · lifecycle
             └────────┬─────────┘
                      │  MemoryProvider
             ┌────────▼─────────┐
             │      mem0        │   embeddings · vector search · ranking
             └──────────────────┘

Die Plattform definiert, was eine Firm Memory bedeutet. Der Provider definiert, wie sie gespeichert und abgerufen wird. MCP definiert, wie Agenten auf sie zugreifen. Genau diese Trennung ist der eigentliche Punkt: Ein zweiter Provider kann eingeführt werden, ohne OpenCode oder den MCP-Vertrag zu ändern.

Related MCP server: AgentBase

Schnellstart

pip install -e '.[mem0,pgvector,rerank,mcp,dev]'
export FIRM_MEM0_PG_DSN='postgresql://mem0:pw@db.internal:5432/mem0'
export FIRM_MEMORY_DOMAINS='execution,mcx'      # this repo's domains
export FIRM_MEMORY_CANDIDATES_PATH='.firm-memory/candidates.json'

from firm_memory import FirmMemory, MemoryScope, MemoryType

memory = FirmMemory.from_env()          # scoped to this checkout + its domains + the firm

for hit in memory.search("why does OMS reject orders after 15:20"):
    print(hit.id, hit.content, hit.provenance.reference)

proposal = memory.propose(
    "Cash strategies stop sending at 15:20 because the exchange rejects after that.",
    type=MemoryType.BUSINESS_RULE,
    scope=MemoryScope(domains=("execution",), repos=("oms", "gateway")),
    reference="mr-4821",
)
# Not stored as knowledge yet — it is queued for a human:
print(proposal.accepted, proposal.candidate_id, proposal.decision.reason)

memory.approvals.approve(proposal.candidate_id, approver="ashish")

Stellen Sie den MCP-Server für die Agenten bereit:

firm-memory-mcp        # stdio; exposes memory_search / memory_get / memory_propose / memory_correct

Die fünf Dinge, die dieses Paket verwaltet

1. Taxonomie

Die Standard-Extraktion eines Providers ist auf Consumer-Assistenten ausgerichtet (Essen, Hobbys, Musik). Unsere ist auf Handelssysteme ausgerichtet. Dreizehn Typen, jeweils mit der Beschreibung, die die Extraktion steuert:

ARCHITECTURE_DECISION · REJECTED_APPROACH · CONVENTION · REVIEW_PATTERN · BUG_FIX · TASK_LEARNING · TOOLING_SETUP · DEPENDENCY_DECISION · PERFORMANCE_FINDING · BUSINESS_RULE · PRODUCTION_ISSUE · OWNERSHIP · TERMINOLOGY

Wird erzwungen, bevor etwas einen Provider erreicht. Beide Schreibweisen führen zum selben Typ – der Elementname (BUSINESS_RULE) und der stabile Wire-Slug (business_rules).

Ebenso wichtig sind die Ausschlüsse: kein Quellcode, keine Diffs oder Stack-Traces; keine Geheimnisse; keine Fakten über einzelne Ingenieure; kein transienter Zustand.

2. Geltungsbereich

Unabhängige Attribute, keine Hierarchie – denn Firmenwissen folgt keinem Baum:

{"firm": true, "domains": ["execution"], "repos": ["oms", "gateway"]}

Ein Memory, das über drei Repos hinwegreicht, wird einmal gespeichert und ist von jedem einzelnen aus erreichbar. Es gibt bewusst **keine Ebene für Einzelne and Ingeneure und keine Ebene für Teams: Dieselbe Frage muss – egal ob. **Daselbe Frage muss – egal von wem sie gestellt wurde. Und eine identity gate? Ich must zurückgeben; eine Identität-Achse würde einen Fakt in Auseinanderdrifftende Kopien zerlegeln.

3. Stufen

Die Lebensdauer-Achse, orthogonal zum Freigabestatus:

Die Suche schließt EPISODIC standardmäßig aus. Dieser Standard ist tragend: Für einen Vektor-Store bedo(fehleder Task-Filter „egal“, night „nicht gesetzt“; oh ihn würde der zwichenzeitige Zusinnand jeder MR in die gewöhnliche Abfrage einfließen. Dafür gibt es einen Vertragstest.

4. Herfarming und Lebenszyklus

Jeder Memory-Eintrag trägt seine Herf einen This ein, sodass ein Entwickler age ein Zitat bis zum MR, Issue oder Interview zurücwerfolgen kann, dass dahinter ist – und es korriegieren kann.

Candidate ─► taxonomy / scope / provenance checks ─► human approval ─► provider.insert()

V1 ist vollständig durchen Menschen freigegeben; die Konfidenz wird von Anfang an erfasét, sodass die Automatisierung spätern ohne Migration eingeschaltet werden kann. Geschäftsregeln, Architekturtentscheidungen, Filmenkonventionen – und wen kein arbeitskritisches gende erfordern always eine Person, unabhänging von der Konfidenz.

Es wird nichts gelösct. Eine Korretur stuf he und flaggt; eine Ablösung benennt den Nachfahren. Die Aufzeichnung, dass eine Entschedung getroffen – und wieder „–“ – Liter erhalten bleiben.

5. Zuvverlässig

Memory ist Best Effort. Lesevonängen six nee: Ein Provider-Ausfall oder ein Bruch desbeschränkten Zeitlimits liefert ein risiko-Ergebnis and a gemessene Kennzahl – so that ein fehlgeschlagener Abruf nie ein Code-Review scheit tragen kann. Schreibvorgänge dürfen Fehler * doch – still **Heraus

• Schreibvorgänge wirfen doch Fehler: ein Memory-Article, das ein Entwickler gerade erfreigegeben hat, stillschweigend zu verwerfen, wäre schlimmer als ein Fehler.

Konfiguration

Plattform-Einstellungen sind Provider-unabhängig; Provider-Einstellungen werden vom Provider selbst gelesen. Genau diese Trennung bewirkt, dass ein Provider-Tausch nur eine Konfigurationsänderung ist.

FIRM_MEMEE_REPO, FIRM_MEE0_TOP_K, FIRM_MEEq_THRESHOL und FIRM_MEE_ FIRM_0WNER werden weiterhin doppelt engaged und bestätigt, damit eine vorhandene Installation sich beim Upgrad ohne Verhalten nicht ändern kann.

Die Bereitstellunget ist selbst gehostet und hat keinen ausgehenden Datenverkehr. Geschäftsregeln wie „MCX-Aufträge laufen immer über Risk Engine A“ liegen näher am Strategie-IP als an Code-Kommentaren, und der Pool erbt das gesamte Zugriffskontrolle über alle Repos, die ihn speisen.

Aufbau

src/firm_memory/
├── models.py          canonical Memory · status · tier
├── taxonomy.py        the firm's vocabulary and its exclusions
├── scope.py           firm / domains / repos
├── provenance.py      where a memory came from
├── lifecycle.py       approval policy and status transitions
├── memory.py          the API agents and applications import
├── config.py          platform settings
├── metrics.py         failure and latency counters
├── repo.py            deterministic repo identity
├── providers/
│   ├── base.py        the interface: insert · search · get · update
│   ├── registry.py    configuration-driven selection
│   ├── inmemory.py    dependency-free provider for tests and local use
│   └── mem0/          namespace · filters · mapping · settings · provider
├── ingestion/
│   ├── approval.py    the human gate
│   └── store.py       where candidates wait
└── mcp/
    ├── tools.py       the four tools (no SDK dependency)
    └── server.py      thin transport adapter

tests/
├── unit/          modules in isolation
├── integration/   the API across layers, incl. provider swap
├── contract/      against the real mem0 filter pipeline
└── mcp/           the agent-facing surface

Entwicklung

Get dev tools

.venv/bin/python -m pytest -q                       # 261 tests (1 skipped without the mcp extra)
.venv/bin/python -m pytest --cov --cov-report=term   # 94% coverage
.venv/bin/python -m ruff check src tests

Die Contract-Tests sind die entscheidenden. Sie lassen unsere Filter durch echte Vorverarbeitung von mem0 und den SQL-Builder von pgvector laufen und sichern dabei die Grenzen, die wir beim Lesen dessen Source interestiert haben – flaches OR-Zweige, flache Metadaten-Schlüssel, Listenwerte die eine von bedeuten, und den Top-Level-Enitäts-Schlüssel, den Memory.search vorrausset. Wenn ein mem0-upgrade einen bricht, schlagen sie laut fehl, statt dass der Pool langsam leer wird.