{"_id":"@4meta5/engram","_rev":"3-c9e7fc5fa3128173b3c26153576f97aa","name":"@4meta5/engram","dist-tags":{"latest":"0.2.2"},"versions":{"0.2.0":{"name":"@4meta5/engram","version":"0.2.0","keywords":["developer-tools","code-search","memory","context","ai-agents","local-first","skill-generation","semantic-search"],"author":{"name":"Patch","email":"patch@bobamatchasolutions.com"},"license":"MIT","_id":"@4meta5/engram@0.2.0","maintainers":[{"name":"4meta5","email":"orlandodowntownhome@gmail.com"}],"homepage":"https://github.com/bobamatcha/engram#readme","bugs":{"url":"https://github.com/bobamatcha/engram/issues"},"bin":{"engram":"dist/cli.js"},"dist":{"shasum":"cee2a419bac3fab7c78dacd4151da11798275034","tarball":"https://registry.npmjs.org/@4meta5/engram/-/engram-0.2.0.tgz","fileCount":187,"integrity":"sha512-nvioucX7LXaXWRtSeJaKGhMhxnxXNFF5liL354UGJqA95wSeShD44DCFqxArJDI0vy6tldp7pQDtI9DFLJuQUw==","signatures":[{"sig":"MEUCIHfHg5epAO+FFV9L1i21nDCTjbeog8hjjVBcThACruypAiEAiH2CtrPW6FfDzNM9cAIdXQuZUrDHmjpJdgAfRH9WD8A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":645736},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"f6ef5defee2b37b85bf9dfdf15d5552697c86d74","scripts":{"cli":"tsx src/cli.ts","dev":"tsc --watch","lint":"eslint src --ext .ts","test":"npm run test --workspaces && vitest run","build":"npm run build:packages && tsc","test:watch":"vitest","build:packages":"npm run build -w @4meta5/semantic-memory && npm run build -w @4meta5/skill-generator"},"_npmUser":{"name":"4meta5","email":"orlandodowntownhome@gmail.com"},"repository":{"url":"git+https://github.com/bobamatcha/engram.git","type":"git"},"workspaces":["packages/semantic-memory","packages/skill-generator"],"_npmVersion":"11.6.2","description":"Cognitive repository for developer memory. Indexes code AND context.","directories":{},"_nodeVersion":"25.2.1","dependencies":{"commander":"^12.0.0","tree-sitter":"^0.21.0","better-sqlite3":"^11.0.0","tree-sitter-typescript":"^0.21.0","@4meta5/semantic-memory":"workspace:*","@4meta5/skill-generator":"workspace:*"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^2.0.0","typescript":"^5.4.0","@types/node":"^20.0.0","@types/better-sqlite3":"^7.6.0"},"_npmOperationalInternal":{"tmp":"tmp/engram_0.2.0_1770014263236_0.4286741460444947","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@4meta5/engram","version":"0.2.1","keywords":["developer-tools","code-search","memory","context","ai-agents","local-first","skill-generation","semantic-search"],"author":{"name":"Patch","email":"patch@bobamatchasolutions.com"},"license":"MIT","_id":"@4meta5/engram@0.2.1","maintainers":[{"name":"4meta5","email":"orlandodowntownhome@gmail.com"}],"homepage":"https://github.com/bobamatcha/engram#readme","bugs":{"url":"https://github.com/bobamatcha/engram/issues"},"bin":{"engram":"dist/cli.js"},"dist":{"shasum":"74b4c3b5126b4eabef13ed551898dae4caa0365c","tarball":"https://registry.npmjs.org/@4meta5/engram/-/engram-0.2.1.tgz","fileCount":205,"integrity":"sha512-9KuSCIbWQ1eLRnWoNFRX+b2GUjZKorwmj4rcB6ZX0lJmi6wXeexf5cbrxHO9VV5PuVM4/mfwK4CeQcmmS/3qpg==","signatures":[{"sig":"MEQCIBcOGLvNPdIFUycWkRdsGqpM9SM0EOWwCq6DBR5Y+9JBAiBd5Gt/KeOgnW59aFZOAlORlVhQ4CM9oRce67L0knknCA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":741716},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"cea2a41725c9705f5d5c964edbf9d626976dd87b","scripts":{"cli":"tsx src/cli.ts","dev":"tsc --watch","lint":"eslint src --ext .ts","test":"npm run test --workspaces && vitest run","build":"npm run build:packages && tsc","test:watch":"vitest","build:packages":"npm run build -w @4meta5/semantic-memory && npm run build -w @4meta5/skill-generator"},"_npmUser":{"name":"4meta5","email":"orlandodowntownhome@gmail.com"},"repository":{"url":"git+https://github.com/bobamatcha/engram.git","type":"git"},"workspaces":["packages/semantic-memory","packages/skill-generator"],"_npmVersion":"11.6.2","description":"Cognitive repository for developer memory. Indexes code AND context.","directories":{},"_nodeVersion":"25.2.1","dependencies":{"commander":"^12.0.0","tree-sitter":"^0.21.0","better-sqlite3":"^11.0.0","tree-sitter-typescript":"^0.21.0","@4meta5/semantic-memory":"workspace:*","@4meta5/skill-generator":"workspace:*"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^2.0.0","typescript":"^5.4.0","@types/node":"^20.0.0","@types/better-sqlite3":"^7.6.0"},"_npmOperationalInternal":{"tmp":"tmp/engram_0.2.1_1770166110114_0.9074511888872325","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@4meta5/engram","version":"0.2.2","description":"Cognitive repository for developer memory. Indexes code AND context.","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"engram":"dist/cli.js"},"scripts":{"build":"npm run build:packages && tsc","build:packages":"npm run build -w @4meta5/semantic-memory && npm run build -w @4meta5/skill-generator","dev":"tsc --watch","test":"npm run test --workspaces && vitest run","test:watch":"vitest","lint":"eslint src --ext .ts","cli":"tsx src/cli.ts"},"workspaces":["packages/semantic-memory","packages/skill-generator"],"keywords":["developer-tools","code-search","memory","context","ai-agents","local-first","skill-generation","semantic-search"],"author":{"name":"Patch","email":"patch@bobamatchasolutions.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/bobamatcha/engram.git"},"engines":{"node":">=20"},"dependencies":{"@4meta5/semantic-memory":"workspace:*","@4meta5/skill-generator":"workspace:*","better-sqlite3":"^11.0.0","commander":"^12.0.0","tree-sitter":"^0.21.0","tree-sitter-typescript":"^0.21.0"},"devDependencies":{"@types/better-sqlite3":"^7.6.0","@types/node":"^20.0.0","tsx":"^4.0.0","typescript":"^5.4.0","vitest":"^2.0.0"},"gitHead":"cea2a41725c9705f5d5c964edbf9d626976dd87b","_id":"@4meta5/engram@0.2.2","bugs":{"url":"https://github.com/bobamatcha/engram/issues"},"homepage":"https://github.com/bobamatcha/engram#readme","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-7b7Nme3/4qF+yayWKUJSsOhGlFfm8oC5AmylXNkbs0KYqdBjxEQFRfMbVGMkh/JL5XOVmSa/PthkELfoP8vUjg==","shasum":"ec76047466a17f330986d7bc076c2d21255a9d60","tarball":"https://registry.npmjs.org/@4meta5/engram/-/engram-0.2.2.tgz","fileCount":59,"unpackedSize":229971,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCJ08XDl6Mq+5uSMlXPMzBWcZYPTQPQGLy6ZFJCIq09uwIgBwbFM2mbkh1iXV7x1AFqfqv365AcLwGQjH/XgUaT8xA="}]},"_npmUser":{"name":"4meta5","email":"orlandodowntownhome@gmail.com"},"directories":{},"maintainers":[{"name":"4meta5","email":"orlandodowntownhome@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/engram_0.2.2_1770166295491_0.3246083431689377"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-02T06:37:43.084Z","modified":"2026-02-04T00:51:35.775Z","0.2.0":"2026-02-02T06:37:43.434Z","0.2.1":"2026-02-04T00:48:30.379Z","0.2.2":"2026-02-04T00:51:35.640Z"},"bugs":{"url":"https://github.com/bobamatcha/engram/issues"},"author":{"name":"Patch","email":"patch@bobamatchasolutions.com"},"license":"MIT","homepage":"https://github.com/bobamatcha/engram#readme","keywords":["developer-tools","code-search","memory","context","ai-agents","local-first","skill-generation","semantic-search"],"repository":{"type":"git","url":"git+https://github.com/bobamatcha/engram.git"},"description":"Cognitive repository for developer memory. Indexes code AND context.","maintainers":[{"name":"4meta5","email":"orlandodowntownhome@gmail.com"}],"readme":"# engram\n\nMemory layer for AI coding agents. Stores context, extracts patterns, generates skills.\n\n[![npm version](https://img.shields.io/npm/v/@4meta5/engram.svg)](https://www.npmjs.com/package/@4meta5/engram)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n```bash\n# Generate a skill from your Claude Code sessions\nnpx @4meta5/engram generate-skill --workspace . --output ./skills\n```\n\n## What It Does\n\n- **Remembers context**: Stores decisions, patterns, and gotchas from coding sessions\n- **Extracts patterns**: Finds which files change together, common commands, error fixes\n- **Generates skills**: Creates markdown skills from session history for Claude Code\n- **Searches semantically**: Hybrid BM25 + vector search with RRF fusion\n\n## Packages\n\n| Package | Path | npm |\n|---------|------|-----|\n| `@4meta5/engram` | `.` | [![npm](https://img.shields.io/npm/v/@4meta5/engram)](https://npmjs.com/package/@4meta5/engram) |\n| `@4meta5/semantic-memory` | `packages/semantic-memory` | [![npm](https://img.shields.io/npm/v/@4meta5/semantic-memory)](https://npmjs.com/package/@4meta5/semantic-memory) |\n| `@4meta5/skill-generator` | `packages/skill-generator` | [![npm](https://img.shields.io/npm/v/@4meta5/skill-generator)](https://npmjs.com/package/@4meta5/skill-generator) |\n\n## Architecture\n\n```mermaid\ngraph TD\n    CLI[\"@4meta5/engram CLI\"] --> SM[\"@4meta5/semantic-memory\"]\n    CLI --> SG[\"@4meta5/skill-generator\"]\n    SG --> Parsers[\"Session Parsers\"]\n    SG --> Extractors[\"Pattern Extractors\"]\n    SG --> Generators[\"Skill Generators\"]\n    SM --> SQLite[\"SQLite + FTS5\"]\n    Parsers --> CC[\"Claude Code\"]\n    Parsers --> OC[\"OpenClaw\"]\n```\n\n## Quick Start\n\n### CLI\n\n```bash\n# Install globally\nnpm install -g @4meta5/engram\n\n# Generate a skill from Claude Code history\nengram generate-skill --workspace /path/to/project --output ./skills\n\n# Search memories\nengram search \"authentication flow\"\n\n# Add a memory manually\nengram add \"Use JWT for API auth, refresh tokens stored in httpOnly cookies\"\n\n# List recent sessions\nengram sessions --days 7\n```\n\n### Library\n\n```typescript\nimport { createMemoryStore, generateProjectSkill } from '@4meta5/engram';\n\n// Memory storage\nconst store = createMemoryStore({ dbPath: './memory.db' });\nawait store.add('JWT tokens for auth', { topics: ['auth'] });\nconst results = store.searchBM25('authentication');\n\n// Skill generation\nconst result = await generateProjectSkill('.', './skills', { days: 30 });\nconsole.log(`Generated: ${result.skillPath}`);\n```\n\n## CLI Reference\n\n### Core Commands (Stable)\n\n| Command | Description |\n|---------|-------------|\n| `search` | Search memories |\n| `add` | Add a memory |\n| `stats` | Show memory statistics |\n| `ingest-git` | Ingest recent git log summaries into memory |\n| `ingest-claude` | Import Claude Code sessions |\n| `sessions` | List session history (Claude Code by default) |\n| `generate-skill` | Generate skill from session history |\n\n### Experimental Commands\n\n| Command | Description |\n|---------|-------------|\n| `summarize` | Extract learnings with LLM (requires Claude Code OAuth) |\n| `evaluate-skill` | Check if sessions warrant skill generation |\n| `mcp` | Start MCP server over stdio |\n| `ingest-openclaw` | Import OpenClaw sessions |\n\n### Authentication (summarize only)\n\nBoth CLI and MCP use Claude Code OAuth credentials:\n- macOS Keychain (`Claude Code-credentials` service)\n- `~/.claude/.credentials.json` (fallback)\n\nIf credentials are expired, they are refreshed automatically. If no credentials are found, open Claude Code and sign in.\n\n### OpenClaw Support\n\nOpenClaw sessions are **off by default**. Use `--openclaw` flag to include:\n\n```bash\nengram generate-skill --workspace . --openclaw\nengram summarize --workspace . --openclaw\nengram sessions --source all  # or --source openclaw\n```\n\nRun `engram <command> --help` for options.\n\n## Memory Maintenance\n\nKeep memory current with lightweight, decoupled workflows.\n\n### Ingest recent git activity\n\n```bash\n# Ingest recent commits from the current repo\nengram ingest-git --days 30\n```\n\n### Ingest multiple repos (helper script)\n\n```bash\n# From this repo\n./scripts/ingest-git-all.sh /path/to/repo1 /path/to/repo2\n```\n\n## Daily/Weekly Routine (Low Friction)\n\nDrop this into your project README or team docs to make Engram stick:\n\n```md\n### Engram Routine\n\n**Daily (end of session):**\n- `engram ingest-git --days 7`\n- `engram add \"one non-obvious learning\" -t gotcha,decision,pattern`\n\n**Before starting a task:**\n- `engram search \"your keywords\"`\n\n**Monthly (per project):**\n- `engram generate-skill --workspace . --days 30 --output ./generated-skills`\n```\n\nFor automation, use a scheduler (e.g. Heartbeat) to run `ingest-git` across repos weekly.\n\n## MCP Server (Experimental)\n\nExpose Engram as a minimal MCP server over stdio.\n\n```bash\nengram mcp --workspace .\n```\n\nAvailable tools:\n\n- `engram.search` — BM25 memory search\n- `engram.add` — add a memory\n- `engram.stats` — memory stats\n- `engram.ingestGit` — ingest recent git log summary\n- `engram.summarize` — summarize recent sessions (requires Claude Code OAuth)\n\n`engram.summarize` inputs:\n\n- `days` (number, default 30)\n- `minConfidence` (number, default 0.5)\n- `includeOpenClaw` (boolean, default false)\n- `openclawAgent` (string, optional)\n\nOptional error wrapper (for clients that prefer tool errors in `result`):\n\n```bash\nengram mcp --workspace . --wrap-errors\n```\n\nWithout `--wrap-errors`, tool failures return `{ error, message }` in the tool result.\n\nSmoke test:\n\n```bash\nnode ./scripts/mcp-smoke.js\n```\n\nExample MCP client config (stdio):\n\n```json\n{\n  \"command\": \"node\",\n  \"args\": [\"/absolute/path/to/engram/dist/cli.js\", \"mcp\", \"--workspace\", \"/path/to/project\"]\n}\n```\n\nPlan + rationale: `docs/MCP_PLAN.md`\n\n## Features\n\n### Semantic Memory (`@4meta5/semantic-memory`)\n\n- BM25 full-text search with SQLite FTS5\n- Optional vector search with embedding providers\n- RRF fusion for hybrid ranking\n- Pluggable storage backends\n\n### Skill Generator (`@4meta5/skill-generator`)\n\n- Parses Claude Code and OpenClaw session formats\n- Extracts file co-edits, tool sequences, error patterns\n- Quality gates filter noise from learnings\n- Trigger detection for automatic skill generation\n\n## Development\n\n```bash\n# Clone and install\ngit clone https://github.com/bobamatcha/engram.git\ncd engram\nnpm install\n\n# Build all packages\nnpm run build\n\n# Run tests\nnpm test\n\n# Run CLI in development\nnpm run cli -- generate-skill --help\n```\n\n## Integration\n\nThis project powers the skill generation in [4meta5/skills-cli](https://github.com/4meta5/skills-cli). Install skills-cli to manage Claude Code skills across projects.\n\n## License\n\nMIT\n\n## Credits\n\nBuilt by [Patch](https://github.com/bobamatcha), an AI, with [Amar](https://github.com/4meta5).\n","readmeFilename":"README.md"}