{"_id":"@agentsoft/agent-memo","name":"@agentsoft/agent-memo","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agentsoft/agent-memo","version":"0.1.0","description":"Embedded vector-based document storage with cross-project impact analysis for coding agents","type":"module","main":"dist/index.js","bin":{"agent-memo":"dist/mcp/cli.js"},"types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest run","test:watch":"vitest","prepare":"husky"},"publishConfig":{"access":"public"},"license":"MIT","packageManager":"pnpm@10.28.2","engines":{"node":">=18"},"dependencies":{"@huggingface/transformers":"^3.4.0","@lancedb/lancedb":"^0.15.0","@modelcontextprotocol/sdk":"^1.28.0","apache-arrow":"^19.0.0","chokidar":"^4.0.0","glob":"^11.0.0","yaml":"^2.7.0","zod":"^4.3.6"},"devDependencies":{"@commitlint/cli":"^20.5.0","@commitlint/config-conventional":"^20.5.0","@types/node":"^25.5.0","husky":"^9.1.7","standard-version":"^9.5.0","typescript":"^6.0.2","vitest":"^4.1.1"},"peerDependencies":{"openai":">=4.0.0"},"peerDependenciesMeta":{"openai":{"optional":true}},"gitHead":"92883a28e11c12bb6ee38779c6b1279b14bf48c2","_id":"@agentsoft/agent-memo@0.1.0","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-MAw2b3gstUIiCl82X/5F10dw074wI0G+c0JQtihY4N9Ta0Fqece3OQFJmdgBLqBMrFwD0fvp0eH+/Z/mKNT1+Q==","shasum":"fa835034a5046e4afa4feef49e523131ae24f16a","tarball":"https://registry.npmjs.org/@agentsoft/agent-memo/-/agent-memo-0.1.0.tgz","fileCount":71,"unpackedSize":119160,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAZ4f/ssZeD4A7Fqm8kEwlgQ4rJfigdmjx4YoTrWFNqhAiBZRv0kaWx/Sx9Cjj5FxPBP4Wj1xfBrmILINGSly/Hj7g=="}]},"_npmUser":{"name":"devchrisvaz","email":"dev.chrisvaz@gmail.com"},"directories":{},"maintainers":[{"name":"devchrisvaz","email":"dev.chrisvaz@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-memo_0.1.0_1774475480507_0.6121426492269788"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-25T21:51:20.423Z","0.1.0":"2026-03-25T21:51:20.670Z","modified":"2026-03-25T21:51:20.871Z"},"maintainers":[{"name":"devchrisvaz","email":"dev.chrisvaz@gmail.com"}],"description":"Embedded vector-based document storage with cross-project impact analysis for coding agents","license":"MIT","readme":"# agent-memo\n\nPersistent vector-based documentation memory for AI coding agents. Ingest project docs, search semantically, analyze cross-project impact, and discover existing service capabilities — all via MCP.\n\n## What it does\n\n- **Semantic search** — Find relevant documentation using natural language queries\n- **Cross-project impact analysis** — Understand the blast radius of changes across projects and layers\n- **Service discovery** — Check what already exists before building something new\n- **Incremental sync** — Re-ingesting skips unchanged files via checksums\n- **Format-aware chunking** — Markdown, OpenAPI, code, and plain text each get optimal chunking\n- **Generic tagging** — Define your own organizational dimensions (layers, teams, modules — whatever fits your workflow)\n\n## Installation\n\n### Claude Code\n\n```bash\nclaude mcp add agent-memo -- npx -y @agentsoft/agent-memo --storage ~/.agent-memo\n```\n\n### Gemini CLI\n\nAdd to `~/.gemini/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-memo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentsoft/agent-memo\", \"--storage\", \"~/.agent-memo\"]\n    }\n  }\n}\n```\n\n### Codex CLI\n\nAdd to `~/.codex/config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-memo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentsoft/agent-memo\", \"--storage\", \"~/.agent-memo\"]\n    }\n  }\n}\n```\n\n## MCP Tools\n\n### memo_ingest\n\nIngest files or directories into the knowledge base.\n\n```\nmemo_ingest({ source: \"./docs\" })\nmemo_ingest({ source: [\"./services/auth\", \"./services/payments\"], project: \"backend\" })\nmemo_ingest({ source: \"./api\", tags: { layer: \"api\", team: \"platform\" } })\n```\n\n### memo_search\n\nSemantic search across ingested documentation.\n\n```\nmemo_search({ query: \"JWT authentication\" })\nmemo_search({ query: \"payment processing\", filter: { tags: { layer: \"api\" } } })\nmemo_search({ query: \"user schema\", limit: 5 })\n```\n\n### memo_analyze\n\nCross-project impact analysis combining vector search with relationship graph traversal.\n\n```\nmemo_analyze({ query: \"change user schema to add email verification\" })\nmemo_analyze({ query: \"remove payment gateway\", depth: 3 })\n```\n\n### memo_find_existing\n\nDiscover existing service capabilities to prevent duplicate implementations.\n\n```\nmemo_find_existing({ capability: \"email sending\" })\nmemo_find_existing({ capability: \"file upload\", filter: { project: \"backend\" } })\n```\n\n### memo_relate\n\nRegister explicit dependencies between documents.\n\n```\nmemo_relate({ sourceId: \"abc123-0\", targetId: \"def456-0\", type: \"consumes\" })\n```\n\n## Configuration\n\nCreate `~/.agent-memo/config.json` to configure tag rules and projects:\n\n```json\n{\n  \"tagRules\": [\n    { \"pattern\": \"docs/api\", \"tags\": { \"layer\": \"api\" } },\n    { \"pattern\": \"docs/architecture\", \"tags\": { \"layer\": \"architecture\" } },\n    { \"pattern\": \"services/auth\", \"tags\": { \"service\": \"auth\", \"team\": \"identity\" } }\n  ],\n  \"projects\": [\n    { \"name\": \"backend\", \"paths\": [\"./services\"] },\n    { \"name\": \"frontend\", \"paths\": [\"./apps/web\"] },\n    { \"name\": \"mobile\", \"paths\": [\"./apps/mobile\"] }\n  ]\n}\n```\n\n**Tag rules** auto-tag documents based on file path patterns. Patterns are case-insensitive substring matches.\n\n**Projects** map file paths to project names for automatic project detection.\n\nTags can also be set via frontmatter in markdown files:\n\n```yaml\n---\nproject: auth-service\ntags:\n  layer: api\n  team: identity\n  domain: authentication\n---\n```\n\nPriority: tag rules (lowest) < frontmatter < explicit overrides (highest).\n\n## Architecture\n\n```\n┌─────────────────────────────────┐\n│        AI Coding Tool           │\n│ (Claude / Gemini CLI / Codex)   │\n├─────────────────────────────────┤\n│       stdio (JSON-RPC)          │\n├─────────────────────────────────┤\n│     MCP Server (5 tools)        │\n├─────────────────────────────────┤\n│          Memo Core              │\n│  Ingestion · Search · Impact    │\n├─────────────────────────────────┤\n│      Ports & Adapters           │\n│  LanceDB · Transformers.js     │\n│  Markdown · OpenAPI · Code      │\n└─────────────────────────────────┘\n```\n\n**Ports (swappable):**\n- `VectorStore` — LanceDB (default), extensible to Pinecone/Qdrant/Weaviate\n- `EmbeddingProvider` — Transformers.js local (default), OpenAI API (optional)\n- `ChunkingStrategy` — Markdown, OpenAPI, Code, PlainText\n\n**Storage:** All data persists at the `--storage` path (default `~/.agent-memo`). LanceDB files, document registry, and relationship graph are stored there. Multiple tool sessions share the same knowledge base.\n\n## Embedding\n\nBy default, agent-memo uses [all-MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2) via Transformers.js for local embeddings (~33MB model, downloaded on first use). No API keys required.\n\nTo use OpenAI embeddings instead, use the library API:\n\n```typescript\nimport { createMemo, OpenAIAdapter } from '@agentsoft/agent-memo'\n\nconst memo = await createMemo({\n  storagePath: './.agent-memo',\n  embedding: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),\n})\n```\n\n## Library API\n\nagent-memo can also be used as a TypeScript library:\n\n```typescript\nimport { createMemo } from '@agentsoft/agent-memo'\n\nconst memo = await createMemo({\n  storagePath: './.agent-memo',\n  tagRules: [\n    { pattern: /docs\\/api/i, tags: { layer: 'api' } },\n  ],\n  projects: [\n    { name: 'my-app', paths: ['./src'] },\n  ],\n})\n\nawait memo.ingest('./docs')\nconst results = await memo.search('authentication')\nconst report = await memo.analyze('change user schema')\nawait memo.dispose()\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-c2e89eff210a26d525791c9ff995208c"}