{"_id":"@4stax/kontxt","_rev":"3-e0ade60704e71bf702755965a8bfc7b4","name":"@4stax/kontxt","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@4stax/kontxt","version":"0.1.0","license":"MIT","_id":"@4stax/kontxt@0.1.0","maintainers":[{"name":"4stax","email":"hello@4stax.com"}],"bin":{"kontxt":"bin/kontxt.js"},"dist":{"shasum":"ed1e74c6b2782dcc6204c0948d35378c0522aece","tarball":"https://registry.npmjs.org/@4stax/kontxt/-/kontxt-0.1.0.tgz","fileCount":42,"integrity":"sha512-lGwF5bTkv9EF6/jjG4pMWATWUkhemF/mwpzU4GF2D6F+dVq9aeZs/LptBqGEU0xCSJWvfccZKMXktiwmGBl2zA==","signatures":[{"sig":"MEUCIEWLkdo6zpGaLCl4p/GrdcNsYGuPJZYn6G/K1sc6tWFjAiEA33UMQN20LAPd8UKjVAugtEFqmUtPMLRIacI76QZb3vA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":103797},"main":"dist/cli/index.js","type":"commonjs","types":"./dist/cli/index.d.ts","engines":{"node":">=18"},"gitHead":"573d32f66ea1b975ae649a4f902d8982aae094e3","scripts":{"dev":"tsx src/cli/index.ts","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"4stax","email":"hello@4stax.com"},"_npmVersion":"8.19.2","description":"Your AI memory layer. Works everywhere.","directories":{},"_nodeVersion":"20.19.2","dependencies":{"ora":"^5.4.1","zod":"^3.22.0","uuid":"^9.0.0","chalk":"^4.1.2","openai":"^4.0.0","commander":"^12.0.0","better-sqlite3":"^9.4.0","@xenova/transformers":"^2.17.2","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","typescript":"^5.4.0","@types/node":"^20.0.0","@types/uuid":"^9.0.0","@types/better-sqlite3":"^7.6.0"},"_npmOperationalInternal":{"tmp":"tmp/kontxt_0.1.0_1774915103722_0.43614069433624003","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@4stax/kontxt","version":"0.1.1","license":"MIT","_id":"@4stax/kontxt@0.1.1","maintainers":[{"name":"4stax","email":"hello@4stax.com"}],"bin":{"kontxt":"bin/kontxt.js"},"dist":{"shasum":"906bb3b7c40eb435c5ee75cd583499fef5d5218f","tarball":"https://registry.npmjs.org/@4stax/kontxt/-/kontxt-0.1.1.tgz","fileCount":76,"integrity":"sha512-hOSkVEITXgMTWIR6k0zG+JTzMWn3SE2gt72BZGJmCkQucYEcBOLGofkUpxAmyDM5qi6jkMOS+VU8Jl/sGBO7+w==","signatures":[{"sig":"MEUCIDxOCtNvpUAGi3Bk2h+jhdvZphiRoxIQBfN69sgOB+ZTAiEAigLbKYVhpTxw6uwuq3FGvzLqSVqITZ/FL1X9YWxnQ0k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":182796},"main":"dist/cli/index.js","type":"commonjs","types":"./dist/cli/index.d.ts","engines":{"node":">=18"},"gitHead":"a3125ad1e7d453ce63c67e5a9c55fe504a3aebde","scripts":{"dev":"tsx src/cli/index.ts","build":"tsc","test:e2e":"bash scripts/e2e-local.sh","prepublishOnly":"npm run build"},"_npmUser":{"name":"4stax","email":"hello@4stax.com"},"_npmVersion":"8.19.2","description":"Your AI memory layer. Works everywhere.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"ora":"^5.4.1","zod":"^3.22.0","uuid":"^9.0.0","chalk":"^4.1.2","openai":"^4.0.0","chokidar":"^3.6.0","commander":"^12.0.0","better-sqlite3":"^9.4.0","@xenova/transformers":"^2.17.2","@supabase/supabase-js":"^2.49.1","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","typescript":"^5.4.0","@types/node":"^20.0.0","@types/uuid":"^9.0.0","@types/better-sqlite3":"^7.6.0"},"_npmOperationalInternal":{"tmp":"tmp/kontxt_0.1.1_1776294985792_0.3199559155758136","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@4stax/kontxt","version":"0.1.2","description":"Your AI memory layer. Works everywhere.","license":"MIT","type":"commonjs","main":"dist/cli/index.js","bin":{"kontxt":"bin/kontxt.js"},"publishConfig":{"access":"public"},"engines":{"node":">=18"},"scripts":{"build":"tsc","prepublishOnly":"npm run build","dev":"tsx src/cli/index.ts","test:e2e":"bash scripts/e2e-local.sh"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","@xenova/transformers":"^2.17.2","better-sqlite3":"^9.4.0","chalk":"^4.1.2","chokidar":"^3.6.0","commander":"^12.0.0","openai":"^4.0.0","ora":"^5.4.1","uuid":"^9.0.0","zod":"^3.22.0"},"devDependencies":{"@types/better-sqlite3":"^7.6.0","@types/node":"^20.0.0","@types/uuid":"^9.0.0","tsx":"^4.21.0","typescript":"^5.4.0"},"types":"./dist/cli/index.d.ts","gitHead":"a3125ad1e7d453ce63c67e5a9c55fe504a3aebde","_id":"@4stax/kontxt@0.1.2","_nodeVersion":"20.20.2","_npmVersion":"8.19.2","dist":{"integrity":"sha512-5It4W9ojvgYM4tTZvoAzxcMH91iaerpwQH32rL7OVszzdNhxu8TCD2rW6bQASqVSRBb4r3xc3AG5zUzPAwTANQ==","shasum":"46fdd91f7aef906e6aef672b91a707b8d05554b3","tarball":"https://registry.npmjs.org/@4stax/kontxt/-/kontxt-0.1.2.tgz","fileCount":68,"unpackedSize":169719,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDjCCAF+k5zU9mQPfobcqVUwVii1e1UUEi5QpOL114RRwIgSc2VZR1IYLHRMEKMmeWdn9En0KCipZ2CWOJWFpLP660="}]},"_npmUser":{"name":"4stax","email":"hello@4stax.com"},"directories":{},"maintainers":[{"name":"4stax","email":"hello@4stax.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kontxt_0.1.2_1776295470983_0.22212981742948967"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-30T23:58:23.634Z","modified":"2026-04-15T23:24:31.255Z","0.1.0":"2026-03-30T23:58:23.878Z","0.1.1":"2026-04-15T23:16:25.960Z","0.1.2":"2026-04-15T23:24:31.147Z"},"license":"MIT","description":"Your AI memory layer. Works everywhere.","maintainers":[{"name":"4stax","email":"hello@4stax.com"}],"readme":"# kontxt\n\nLocal-first continuity for AI work across chats, tools, and providers.\n\n`kontxt` keeps project context on your machine, maintains a small living project state in Markdown, and prepares compact carry-forward context for new sessions. It is designed for workflows where you switch between tools such as Cursor, Claude Desktop, Codex, or web chat products and do not want to restart from zero every time.\n\n**npm:** [`@4stax/kontxt`](https://www.npmjs.com/package/@4stax/kontxt)  \nThe installed CLI command is still `kontxt`.\n\n## Security\n\n`kontxt` is local-first by default.\n\n- Vault data is stored under `~/.kontxt/`\n- Project state is stored in local `.kontxt/*.md` files\n- Session history is stored in `~/.kontxt/session-state.json`\n- `~/.kontxt` files are created with owner-only permissions where supported\n- No cloud sync is part of the default workflow\n- `session start --mode fresh` disables automatic carry-forward for a clean session\n\nOperational guidance:\n\n- Use `--mode ask` when reviewing carry-forward context before injection matters\n- Treat any transcript piped into `session end` or `capture` as data you are intentionally storing locally\n- If you use an OpenAI API key, it is stored locally in `~/.kontxt/config.json`\n- The local machine account is the primary trust boundary for stored memory\n\nAdditional references:\n\n- [Security Notes](SECURITY.md)\n- [VS Code Extension Architecture](docs/vscode-extension.md)\n\n## What It Does\n\n- Stores durable context locally in `~/.kontxt/vault.db`\n- Keeps a project state in `.kontxt/CONTEXT.md`, `DECISIONS.md`, `FACTS.md`, and `TIMELINE.md`\n- Retrieves relevant context for a new session\n- Supports `auto`, `ask`, and `fresh` continuity modes\n- Captures the outcome of a finished session and updates local state\n- Exposes MCP tools for compatible clients\n\n## Install\n\nRequirements:\n- Node.js `>=18`\n\nOne-off usage:\n\n```bash\nnpx -y @4stax/kontxt init\n```\n\nGlobal install:\n\n```bash\nnpm install -g @4stax/kontxt\nkontxt init\n```\n\nOptional: save an OpenAI key for higher-quality embeddings and transcript extraction:\n\n```bash\nkontxt init --key sk-...\n```\n\nWithout an API key, `kontxt` uses:\n1. Transformers.js local embeddings when available\n2. Ollama local models when available\n3. A weaker lexical fallback when neither is available\n\n## Quick Start\n\nInside a repo:\n\n```bash\nkontxt living init --dir .\nkontxt living focus \"Describe the current project focus\" --dir .\nkontxt living task \"Add the next concrete task\" --dir .\nkontxt watch --dir .\n```\n\nAt the start of a new AI session:\n\n```bash\nkontxt session start \"continue working on auth flow\" --mode ask --dir .\n```\n\nAt the end of a session:\n\n```bash\ncat transcript.txt | kontxt session end --provider claude-web --dir .\n```\n\nSearch the current project state or stored memory:\n\n```bash\nkontxt search \"what changed this week?\" --limit 5\nkontxt search \"what decisions have we made about auth?\" --limit 5\n```\n\n## Daily Workflow\n\nRecommended loop:\n\n1. Start `kontxt watch --dir .` in the project.\n2. Keep `.kontxt/*.md` as the working state for the project.\n3. Before starting a new chat, run `kontxt session start ...`.\n4. Inject the returned summary only if the session should continue prior work.\n5. After the session, run `kontxt session end` on the transcript.\n\nThis keeps the project timeline, decisions, and durable context up to date locally.\n\n## Continuity Modes\n\n`kontxt session start` supports three modes:\n\n- `--mode auto`\n  Inject automatically when relevance is strong.\n- `--mode ask`\n  Prepare a summary, but expect the caller or UI to confirm before injecting. This is the safest default.\n- `--mode fresh`\n  Do not inject prior context automatically.\n\nExample:\n\n```bash\nkontxt session start \"continue debugging the API timeout issue\" --mode ask --provider cursor --dir .\nkontxt session start \"fresh start on a new idea\" --mode fresh --provider claude-web --dir .\n```\n\n## Living Project Files\n\n`kontxt living init` creates:\n\n- `.kontxt/CONTEXT.md`\n- `.kontxt/DECISIONS.md`\n- `.kontxt/FACTS.md`\n- `.kontxt/TIMELINE.md`\n\nThese files are the human-readable project state. `kontxt` can update them directly and ingest them back into the local vault.\n\nCommands:\n\n```bash\nkontxt living init --dir .\nkontxt living focus \"Current focus text\" --dir .\nkontxt living task \"Next task\" --dir .\nkontxt living fact \"Stable fact\" --dir .\nkontxt living decision \"Short title\" --decision \"Final decision text\" --context \"Optional context\" --dir .\nkontxt living note \"What changed today\" --dir .\n```\n\nWhen `kontxt watch --dir .` is running, edits to these files are re-ingested automatically.\n\n## Session Commands\n\n### Start\n\nPrepare continuity for a new session:\n\n```bash\nkontxt session start \"<task>\" [options]\n```\n\nUseful options:\n\n- `--mode ask|auto|fresh`\n- `--provider <name>`\n- `--dir <path>`\n- `--project <name>`\n- `--limit <n>`\n- `--json`\n\nExample:\n\n```bash\nkontxt session start \"continue building the npm package\" --mode ask --provider codex --dir .\n```\n\n### End\n\nCapture a completed session:\n\n```bash\nkontxt session end [options]\n```\n\nInput:\n- `--file <path>` to read a transcript file\n- or pipe the transcript over stdin\n\nUseful options:\n\n- `--provider <name>`\n- `--dir <path>`\n- `--project <name>`\n- `--limit <n>`\n- `--json`\n\nExample:\n\n```bash\ncat transcript.txt | kontxt session end --provider claude-web --dir .\n```\n\n`session end` will:\n- extract durable facts, decisions, and progress notes\n- store them in the local vault\n- update living Markdown where applicable\n- record session metadata for future continuity\n\n## Search And Memory Commands\n\n```bash\nkontxt add \"The project uses FastAPI and PostgreSQL\" --type fact --project my-app\nkontxt search \"what stack are we using?\" --limit 5\nkontxt list --project my-app\nkontxt edit <id> \"Updated memory text\"\nkontxt delete <id>\nkontxt vacuum\n```\n\nMemory types:\n- `fact`\n- `preference`\n- `project`\n- `decision`\n- `skill`\n- `episodic`\n\n## Capture Commands\n\nCapture a transcript manually:\n\n```bash\ncat conversation.txt | kontxt capture --project my-app\nkontxt capture --file conversation.txt --project my-app\n```\n\nScan a repo for project facts:\n\n```bash\nkontxt scan --dir . --project my-app\n```\n\nNotes:\n- Transcript extraction is better with an OpenAI key or Ollama.\n- Without them, `kontxt` falls back to heuristics.\n\n## MCP\n\nStart the MCP server on stdio:\n\n```bash\nkontxt serve\n```\n\nMain MCP tools:\n\n- `get_relevant_context`\n- `search_memories`\n- `list_memories`\n- `delete_memory`\n- `auto_capture`\n- `store_memory`\n- `store_conversation_summary`\n- `get_user_profile`\n\n### Cursor\n\n`~/.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"kontxt\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@4stax/kontxt\", \"serve\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\n`~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"kontxt\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@4stax/kontxt\", \"serve\"]\n    }\n  }\n}\n```\n\n`kontxt init` will try to write these configs automatically.\n\n## Storage\n\nLocal files:\n\n- `~/.kontxt/vault.db`\n- `~/.kontxt/config.json`\n- `~/.kontxt/session-state.json`\n- `~/.kontxt/models/` for cached local embedding models\n\nProject-local files:\n\n- `.kontxt/CONTEXT.md`\n- `.kontxt/DECISIONS.md`\n- `.kontxt/FACTS.md`\n- `.kontxt/TIMELINE.md`\n\nBy default, data stays local.\n\n## Troubleshooting\n\nIf `better-sqlite3` native bindings fail after install:\n\n```bash\nnpm rebuild better-sqlite3\n```\n\nCheck current setup:\n\n```bash\nkontxt status\n```\n\nIf local embeddings are unavailable, `kontxt` will still run using the lexical fallback, but retrieval quality will be lower.\n\n## Verification\n\n```bash\nnpm run build\nnpm run test:e2e\n```\n\nThe smoke test covers:\n- init\n- add/search\n- living file management\n- watch/ingest\n- session start/session end\n- status\n\n## License\n\nMIT\n","readmeFilename":"README.md"}