@futdevpro/fdp-agent-memory

Local-first, vektor-alapú, többtáras agent-memória MCP-szerver. Bármely MCP-kliens (Claude Desktop / Claude Code / CCAP) egységes read / write / capabilities felületen ér el tartós, kereshető tudást — lokálisan futó, saját MongoDB-vel, auth nélkül.

1. Mi ez?

Az FDP Agent Memory egy publikus NPM package + lokális MCP-szerver: a saját gépeden futó, vektor-alapú RAG-memória, amit az agented mentésre (write) és visszakeresésre (read) használ. A szerver az MCP-kliensnek pontosan 3 toolt hirdet:

• read — tudás keresése/lekérése (egylépcsős, multi-tábla + multi-query, dense-jelzéssel),
• write — tudás mentése / módosítása / törlése / scan / re-embed / import (pontosan 1 tár),
• capabilities — a ritkán használt speciális eszközök (diagnosztika/statisztika/inspekció/ karbantartás/import/debug) felderítése + meghívása EGYETLEN tool-on át (context-tisztaság).

6 fő tár (rules / documents / codebase / knowledge / coding_patterns / memory) + egy reference helper (alias/fogalom-feloldás). A tárak/mezők részleteit lásd a design-doksiban (__specifications/_design/dsgn-001). A vektorok a saját MongoDB-ben élnek, és boot-kor egy in-memory pool-ba hidratálódnak — NINCS Atlas-dependencia.

Boundary: nincs auth / jogosultságkezelés (lokális, single-user); FDP Templates package nélkül (Pure Dynamo). Az MCP-transport MVP1-ben stdio (nincs hálózati port az MCP-felületnek; a 39265-ös port a REST/UI réteghez tartozik). HTTP/SSE transport későbbi fázis (BACKLOG).

2. Install

npm i -g @futdevpro/fdp-agent-memory
# vagy pnpm-mel:
pnpm add -g @futdevpro/fdp-agent-memory

A bin neve fam. Smoke-teszt:

fam --version
fam --help        # listázza a parancsokat

3. Prerequisites

• Node 20.12+ (a ~/.fam/.env betöltéséhez; engines.node >= 20).
• MongoDB — lokális / saját (NEM Atlas). Lásd §5.
• Embedding-provider — OpenAI (API-kulcs) vagy LM Studio (lokális, kulcs nélküli). Lásd §6.

4. Beállítások — hol és hogyan

📘 A teljes, lépésenkénti útmutató a csomag része: docs/CONFIGURATION.md (minden kulcs, embedding-receptek — köztük felhasználónév+jelszóval védett szolgáltató —, hibaelhárítás).

A beállítások helye: a gép-szintű ~/.fam/.env (Windowson: a felhasználói mappa .fam almappájában). A csomag frissítése ezt nem érinti. Sorrend, ha egy kulcs több helyen is szerepel: a futtatáskor megadott érték > ~/.fam/.env > a telepített csomag saját .env-je > a munkakönyvtár .env-je.

fam init      # kitöltendő, magyarázó sablont ír a ~/.fam/.env-be (meglévő fájlt NEM ír újra)
fam doctor    # név szerint megmondja, mi hiányzik, mi hibás, és melyik kulcs honnan jött (érték nélkül)

Minimális példa (helyi Ollama):

EMBEDDING_PROVIDER=openai-compatible
EMBEDDING_BASE_URL=http://localhost:11434/v1
EMBEDDING_MODEL=nomic-embed-text
# MONGODB_URI=mongodb://127.0.0.1:27017   (ez az alapérték)

A futás-idejű minőségi paraméterek (topK / minScore / chunk-méret / overlap / dense-küszöb / embedding-cost-cap) NEM env-var-ok, hanem DB-backed config (global/table/scope precedenciával — fam config set --key … --value …). Az env csak az infra-csatlakozást + a provider-választást adja.

5. MongoDB setup (saját, NEM Atlas)

A FAM a saját MongoDB-det használja (saját Memory Vector Search — nincs Atlas Vector Search dependencia). Indíts egy lokális Mongo-t:

# natív mongod:
mongod --dbpath ./data/db --port 27017

# vagy Docker:
docker run -d --name fam-mongo -p 27017:27017 mongo:8

Ha a MongoDB nem a helyi szabványos porton fut, állítsd be a MONGODB_URI-t a ~/.fam/.env-ben (§4), majd:

fam test-db

A collection-ök (fam_rules, fam_documents, … fam_config) a szerver első indításakor automatikusan létrejönnek.

6. Embedding provider setup

Bármely OpenAI-kompatibilis végpont (LM Studio, Ollama, saját vagy bérelt szerver) vagy az OpenAI. A belépés módja beállítható: nincs · API-kulcs (Bearer) · felhasználónév + jelszó (HTTP Basic).

EMBEDDING_PROVIDER=openai-compatible
EMBEDDING_BASE_URL=http://szerver.example:32909/utvonal/v1
EMBEDDING_MODEL=nomic-embed-text
EMBEDDING_USERNAME=…
EMBEDDING_PASSWORD=…

A régi LMSTUDIO_BASE_URL / LMSTUDIO_API_KEY / LMSTUDIO_EMBEDDING_MODEL nevek tovább működnek. Receptek minden esetre és a hibaüzenetek jelentése: docs/CONFIGURATION.md §5 és §7.

fam test-embedding   # próba-embedding a beállított szolgáltatóval

7. MCP client config

Mindkét kliens a fam start stdio-belépőt indítja. Copy-paste-elhető config-példák a package-ben: build/src/_assets/mcp-client-config/ (claude_desktop_config.json + mcp.json — utóbbit mentsd .mcp.json néven a projekt-gyökérbe). Röviden:

Claude Desktop — claude_desktop_config.json (OpenAI-preset):

{
  "mcpServers": {
    "fdp-agent-memory": {
      "command": "fam",
      "args": ["start"],
      "env": {
        "MONGODB_URI": "mongodb://127.0.0.1:27017",
        "MONGODB_DB_NAME": "fdp_agent_memory",
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-large"
      }
    }
  }
}

Claude Code — .mcp.json (projekt-gyökér, LM Studio-preset):

{
  "mcpServers": {
    "fdp-agent-memory": {
      "command": "fam",
      "args": ["start"],
      "env": {
        "MONGODB_URI": "mongodb://127.0.0.1:27017",
        "MONGODB_DB_NAME": "fdp_agent_memory",
        "EMBEDDING_PROVIDER": "lmstudio",
        "LMSTUDIO_BASE_URL": "http://127.0.0.1:1234/v1",
        "LMSTUDIO_EMBEDDING_MODEL": "nomic-embed-text-v1.5"
      }
    }
  }
}

Ha a fam nincs a PATH-on: "command": "npx", "args": ["-y", "@futdevpro/fdp-agent-memory", "start"]. Az env-blokk felülírja a .env-et a kliens-indított folyamatban (self-contained kliens). Csatlakozás után az agent pontosan 3 toolt lát (read/write/capabilities) — a speciálisak capabilities-en át.

8. First run

fam init            # interaktív bootstrap: .env + provider-preset + Mongo-URI
fam create-config   # DB-backed config seedelése reasonable default-okkal
fam start           # az MCP-szerver indítása stdio-n (CSAK a szerver)

fam start az MCP-szervert stdio-n ÉS a REST/UI réteget indítja (port 39265). A beépített admin UI a http://localhost:39265/api/app alatt érhető el — a szerver szolgálja ki, nincs külön kliens-process (egy fam start = teljes lokál felület). Ez az a parancs, amit az MCP-kliens config command-ja is meghív. (Alternatíva: docker compose -f docker-compose.local.yml up — ugyanez konténerből, lokál Mongo-val.)

9. Health check

fam doctor

A doctor az egyetlen ajánlott health-check lépés: aggregálja az env / mongodb / config / embedding / vector / collections rétegek állapotát. Zöld kimenet (✓ minden soron) = kész a kliens-csatlakozásra. Minden FAIL/WARN mellé KONKRÉT fix-tipp jár (néma hiba tilos). A többi diagnosztika (validate-env / test-db / test-embedding) a doctor egy-egy al-checkjére delegál.

10. Troubleshooting

| Tünet | Valószínű ok | Fix | |---|---|---| | fam doctor → DB hiba (FAM-DB-CONNECT-001) | Mongo nem fut / rossz MONGODB_URI | Indítsd a mongod-ot; ellenőrizd a URI-t; fam test-db. | | fam doctor → embedding hiba (FAM-EMB-PROVIDER-*) | provider/kulcs/baseUrl rossz | OpenAI-nál ellenőrizd OPENAI_API_KEY-t; LM Studio-nál a futó szervert + betöltött modellt; fam test-embedding. | | MCP-kliens nem látja a szervert | rossz command/PATH | Globális telepítés (npm i -g …) vagy npx -y @futdevpro/fdp-agent-memory start; ellenőrizd a kliens-config env-jét (§7). | | Az agent túl sok toolt lát | nem a 3-tool felület | Csak read/write/capabilities hirdetett; a többi capabilities-en át. | | CONNECT_TIMEOUT / „connection timed out after 30000ms", de a /api/health él | terhelt gép, lassú kapcsolódás | A munka nem áll meg: REST-fallback (§10a). Az ok a kliens MCP-naplójában látszik (§10a vége). | | FAM-REF-RESOLVE-* hiba write-on | feloldatlan + bizonytalan scope | A hiba felsorolja a kandidátusokat; hozz létre reference-bejegyzést, vagy adj explicit scope-ot. | | dense-warning minden read-en | túl tág query/scope | Szűkíts scope-ra/tag-re a read-válasz suggestions szerint. |

Minden hiba persistált (fam_errors), fam errors-szal vagy az UI-n lekérdezhető; a hibakódok formája FAM-<SERVICE>-<METHOD>-NNN. Néma hiba sehol.

10a. Ha az MCP-kapcsolat kiesik — REST-fallback (olvasás ÉS írás)

Az MCP-kliens a kapcsolódásra 30 s-ot vár. Terhelt gépen ez kifuthat (CONNECT_TIMEOUT), miközben a FAM szerver hibátlanul fut — ilyenkor más MCP-szerverek is jellemzően egyszerre esnek ki. A tudás ettől még elérhető: ugyanaz a három művelet REST-en is hívható, ugyanazzal a törzzsel, mint az MCP-n.

1. Előbb nézd meg, él-e a szerver (ez dönt, nem az MCP-hiba):

curl -s http://127.0.0.1:39265/api/health

• ready: true → a szerver kész; a hiba a kapcsolódásban van → használd a REST-et (lent).
• ready: false → még tölt (hydration.pendingTables); a kész tárak már kérdezhetők, a többi pár perc.
• a bootId a futó példány azonosítója — ha két mérés között megváltozik, a szerver közben újraindult.

2. Olvasás — POST /api/read:

curl -s -X POST http://127.0.0.1:39265/api/read -H "Content-Type: application/json" \
  -d '{"queries":[{"tables":["rules","memory"],"query":"hogyan commitolunk","topK":5}],"includeContent":true}'

3. Írás — POST /api/write (a scopePath elemei layer + rawName párok):

curl -s -X POST http://127.0.0.1:39265/api/write -H "Content-Type: application/json" \
  -H "X-FAM-Agent: my-agent" -H "X-FAM-Session: <session-azonosító>" \
  --data-binary @lesson.json

{
  "table": "memory",
  "operation": "create",
  "kind": "lesson",
  "scopePath": [{ "layer": "organization", "rawName": "MyOrg" }, { "layer": "project", "rawName": "my-project" }],
  "tags": ["példa"],
  "content": "A megtanult tény vagy döntés, a mérésével együtt."
}

⚠️ Buktatók: a query-szintű mezők (topK, minScore, ruleScopeFilter …) a queries[] elemein belül mennek; egy ismeretlen felső szintű kulcsot a válasz első hints sora megnevez. Egy relatív scan.path a hívó abszolút workspacePath-jához oldódik — workspacePath nélkül FAM-VAL-WRITE-004 hibát kapsz. A write fields-ében a rendszer szerkezeti mezői (_id, table, content, scopePath, contentVector, embeddingModel, embeddingStatus, sourceFilePath, ingestRunId) nem írhatók felül ([FAM-WRITE-FIELD-002]); a szöveges fields.source a source.locator-ba kerül ([FAM-WRITE-FIELD-001]). Ha a bejegyzés mentve, de a mögötte lévő fájl nem: [FAM-WRITE-PARTIAL-001]. Windows-os shellben a törzset fájlból (--data-binary @fájl.json) küldd — a parancssori idézőjelek és a \ könnyen érvénytelen JSON-t adnak (a szerver ezt FAM-AGENT-INPUT-001-gyel jelzi, és ilyenkor semmit nem ír).

A lassú kapcsolódás okának felderítése: a FAM az MCP-kliens naplójába (stderr) az első sorokban kiírja az indulás fázisait, pl. [indulás-fázisok: node→kód 25 ms · modulok 2033 ms · primary-próba 157 ms · össz 2215 ms]. Claude Code alatt ezek a naplók: %LOCALAPPDATA%/claude-cli-nodejs/Cache/<projekt>/mcp-logs-fdp-agent-memory/.

11. Capability discovery

A speciális eszközök a capabilities tool-on át (NEM a hirdetett 3-ban):

# az MCP-kliensből (capabilities tool):
{ "action": "list" }                                       # a teljes katalógus (kategóriánként)
{ "action": "describe", "name": "get_table_stats" }        # egy eszköz schema-ja
{ "action": "invoke",   "name": "get_scope_tree" }         # egy eszköz futtatása

# CLI-ból:
fam stats          # tár-statisztikák
fam errors         # persistált hibák

A 6 kategória: config-diagnostics (validate_environment / test_mongodb_connection / test_vector_search / get_config_status / get_embedding_config / test_embedding_provider), high-level-stats (get_table_stats / get_scope_tree / get_reference_stats / get_embedding_cost_stats / get_layer_stats / get_storage_usage), inspection (list_tables / list_scopes / list_scan_runs / list_errors / list_kinds_tags / list_recent_writes), maintenance (reembed_table / reembed_scope / rebuild_reference_index / repair_scope_links / deduplicate_entries), import-migration (preview_claude_mem_import / map_claude_mem_entries / import_claude_mem / run_import / rollback_import), debug (trace_scope_resolution / trace_reference_expansion / explain_search / inspect_chunk / inspect_embedding).

repair_scope_links és deduplicate_entries MVP1-ben dry-run-only (diagnosztikus AUDIT, NEM ír); a destruktív write-ág későbbi fázis (dryRun:false → clear BACKLOG-hiba).

12. CLI reference

| Parancs | Mit csinál | |---|---| | fam init | Interaktív bootstrap: .env + provider-preset + Mongo-URI + alap-config. | | fam doctor | Aggregált health-check (env/mongodb/config/embedding/vector/collections). | | fam start | Az MCP-szerver indítása stdio-n (alias: fam start-server). | | fam read | Tudás keresése (read core-tool CLI-tükre). | | fam write | Tudás mentése/módosítása/törlése (write core-tool). | | fam scan | Fájl/mappa/projekt scan + chunk + embed. | | fam import claude-mem … | claude-mem migráció (preview→map→run→rollback; alias: fam migrate). | | fam config | DB-backed config get/set (global/table/scope). | | fam stats | Tár-statisztikák. | | fam errors | Persistált hibák listája + "kezelve" jelölés. | | fam validate-env | (alias) a doctor env al-checkje. | | fam test-db | (alias) a doctor mongodb al-checkje. | | fam test-embedding | (alias) a doctor embedding al-checkje. | | fam create-config | DB-backed config seedelése default-okkal + preset. | | fam seed-example | Minta-bejegyzések + scope-lánc + reference-aliasok (smoke/demo). |

Globális opciók: --json (gépi kimenet), --server-url <url> (env: FAM_SERVER_URL), --quiet.

13. Migration (claude-mem)

A claude-mem memóriák egyirányú beolvasása (preview→map→run→rollback):

fam import claude-mem --preview          # nem-destruktív összegzés + dedup-előrejelzés
fam import claude-mem                     # tényleges import egy batchId alatt (dedup-skip + embed)
fam import claude-mem --rollback <batch>  # egy batch visszavonása (soft-delete)

Egyirányú (claude-mem → FAM): nincs reverse/export. Részletek: __specifications/_design/dsgn-009.

14. Architecture & links

MCP-kliens (Claude Desktop/Code) ──stdio── fam start (MCP-szerver)
                                              ├── read  ──► Retrieval pipeline (vektor + weight + minScore)
                                              ├── write ──► CRUD / scan / re-embed / import
                                              └── capabilities ──► registry (6 kategória, discoverable)
                                                       │
                                              MongoDB (saját) ── boot ──► in-memory vektor-pool (LVS)

• __specifications/_design/dsgn-001 — adatmodell (6 tár + reference).
• dsgn-002 — scope + reference feloldás. dsgn-005 — read/dense viselkedés.
• dsgn-006 — embedding + Memory Vector Search. dsgn-007 — DB-backed config.
• dsgn-009 — claude-mem migráció. dsgn-010 — CLI. dsgn-012 — setup/packaging (ez a README).

Build & teszt (fejlesztőknek)

pnpm run prep            # pnpm i
pnpm run build-base      # rimraf ./build && tsc && copy-assets  (rimraf KÖTELEZŐ — partial-publish guard)
pnpm run build           # build-base + jasmine
pnpm test                # jasmine
pnpm run build-docker    # Dockerfile

Publishing

Ez egy publikus package (publishConfig.access: "public", scoped @futdevpro/fdp-agent-memory). A main/types a build/-re mutat, a files csak build + bin + README.md (nem ship-elünk forrást/teszt-fixtúrát). A deps Pure Dynamo (@futdevpro/fsm-dynamo + @futdevpro/nts-dynamo) — FDP Templates nincs.

npm-publish — SZÁNDÉKOS itt (ADR-004): a workspace/TEMPLATE-projects "no npm-publish" default (feedback_no_package_lib_in_templates) egy TEMPLATE-projekt-default, ami ITT NEM érvényes — a FAM publikus package, a publish szándékos és megengedett.

Publish-path (a publishConfig.access: "public" miatt nem kell --access public flag):

pnpm run build      # build-gate: rimraf ./build && tsc && jasmine — ZÖLD kötelező
npm pack            # dry-run: a tarball-tartalom = files ([build, bin, README.md])
npm publish

Boundary (ADR-004)

• Deps: CSAK @futdevpro/fsm-dynamo + @futdevpro/nts-dynamo (+ runtime: express/mongoose/openai/axios/…).
• FDP-Templates package TILOS (fdp-templates / nts-fdp-templates / ngx-fdp-templates).
• NINCS auth — nincs JWT/bcrypt, nincs login/register/user route, nincs auth guard/interceptor.
• Server-bázis: class App extends DyNTS_App (NEM FDPNTS_App).