@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+ (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. Env setup

A szerver process.env-ből + a .env-ből tölt (a Dynamo env-loader olvassa a .env-et — prod-kódban NINCS dotenv import). Minta .env:

# MongoDB (saját / lokális — NEM Atlas)
MONGODB_URI=mongodb://127.0.0.1:27017
MONGODB_DB_NAME=fdp_agent_memory

# Embedding provider: lmstudio (DEFAULT — lokális, ingyenes, offline) | openai
EMBEDDING_PROVIDER=lmstudio
LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1
LMSTUDIO_EMBEDDING_MODEL=nomic-embed-text-v1.5

# (OpenAI preset esetén helyette:)
# EMBEDDING_PROVIDER=openai
# OPENAI_API_KEY=sk-...
# OPENAI_EMBEDDING_MODEL=text-embedding-3-large

# Portok (a REST/UI réteg; NEM az MCP-stdio)
FAM_SERVER_PORT=39265
FAM_CLIENT_PORT=4226

Teljes env-var referencia

| Env-var | Kötelező | Default | Leírás | |---|---|---|---| | MONGODB_URI | igen | — | Saját MongoDB connection string (NEM Atlas), pl. mongodb://127.0.0.1:27017. | | MONGODB_DB_NAME | igen | fdp_agent_memory | Adatbázis-név (collection-ök: fam_*). | | EMBEDDING_PROVIDER | igen | lmstudio | lmstudio (DEFAULT — lokális) | openai — az aktív embedding-provider. | | OPENAI_API_KEY | ha provider=openai | — | OpenAI API-kulcs. | | OPENAI_EMBEDDING_MODEL | nem | text-embedding-3-large | OpenAI embedding-modell. | | LMSTUDIO_BASE_URL | ha provider=lmstudio | http://127.0.0.1:1234/v1 | LM Studio OpenAI-kompatibilis endpoint. | | LMSTUDIO_EMBEDDING_MODEL | ha provider=lmstudio | — | A betöltött embedding-modell neve. | | FAM_SERVER_PORT | nem | 39265 | REST/UI szerver-port (NEM az MCP-stdio). | | FAM_CLIENT_PORT | nem | 4226 | Angular UI dev-port (külön kliens-app). | | FAM_CONFIG_OVERRIDE | nem | — | Opcionális boot-time config-override JSON-path (a DB-backed config-on felül). |

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 …). Az env csak az infra-csatlakozást + a provider-választást adja.

Az env validálása: fam validate-env.

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

Állítsd be a MONGODB_URI-t + MONGODB_DB_NAME-et a .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

Két ajánlott preset (fam init / fam create-config egyikét alkalmazza):

OpenAI (cloud, magasabb minőség):

EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_EMBEDDING_MODEL=text-embedding-3-large

LM Studio (lokális, ingyenes, offline — OpenAI-kompatibilis HTTP endpoint):

EMBEDDING_PROVIDER=lmstudio
LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1
LMSTUDIO_EMBEDDING_MODEL=nomic-embed-text-v1.5

Validálás (a megfelelő env-vel) — cost-jelzéssel:

fam test-embedding

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. | | 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.

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).