@contextline/contextline 0.1.1 → 0.2.0

package/README.md

@@ -1,178 +1,154 @@
-# ContextLine
-
-ContextLine is a local-first, filesystem-backed memory layer for MCP-capable AI assistants.
-
-It gives an assistant a small quick-memory file, links into deeper Markdown memory files, and a single MCP tool for reading and writing memory. The server stores and retrieves files; the host model decides what is worth remembering.
-
-For product context and examples, see [Why ContextLine Exists](docs/why-contextline.md).
-
-## Install
-
-```sh
-npm install -g contextline
-contextline setup
-```
-
-The install step prints a reminder to run `contextline setup`. Setup is explicit because it creates local memory files and host integration config.
-
-## Quick Start With Codex
-
-From the project where you want memory enabled:
-
-```sh
-contextline setup
-codex
-```
-
-By default, setup stores memory in `./.contextline`, detects supported hosts, and configures Codex when available.
-
-Setup creates:
-
-- `.contextline/` for local memory
-- `.codex/hooks.json` for the Codex `SessionStart` hook
-- `.codex/hooks/contextline-hook.mjs` for the hook command
-- `.codex/config.toml` for the ContextLine MCP server
-
-On session start, Codex gets a short instruction to call the `contextline` MCP tool with action `hydrate`. The returned instructions tell the main session how to use quick memory and periodically save durable memory.
-
-## What Gets Stored
-
-ContextLine writes plain Markdown:
-
-```text
-.contextline/
-  L1_Quick.md
-  L2_Deep/
-    person_user.md
-    project_contextline.md
-    area_work.md
-    preference_media.md
-  L3_Details/
-    L3_2026_05.md
-  maintenance/
-    proposals/
-  contextline_instructions.md
-  config.json
-```
-
-The cache model is:
-
-- `L1_Quick.md`: compact facts, summaries, and active pointers.
-- `L2_Deep/`: richer fact files per important person, object, project, place, preference area, event, or decision thread.
-- `L3_Details/`: timestamped specifics, receipts, and supporting history.
-
-V1 uses flat L2 filenames with semantic prefixes, such as `person_`, `project_`, `area_`, `place_`, `preference_`, `decision_`, `event_`, and `org_`.
-
-Topology rules:
-
-- L1 may link only to L2 files.
-- L2 may link only to L3 detail files.
-- L3 files are terminal detail files and must contain no wiki links.
-- L1 memory lines should link to relevant L2 files.
-- L2 memory lines should link to relevant L3 detail files when supporting detail exists.
-
-## CLI
-
-```sh
-contextline setup [--host codex|auto|none] [--root .contextline]
-contextline init [root]
-contextline hydrate [root]
-contextline validate [root]
-contextline inspect [root]
-contextline append "text" --date 2026-05-24 [root]
-contextline update-deep <file> <fact-text> <detail-file> [root]
-contextline update-index <index-line> <files...> --root <root>
-contextline hook --root <root>
-```
-
-## MCP Tool
-
-The V1 MCP surface exposes one tool:
-
-- `contextline`
-
-Use the `action` field for operations:
-
-- `hydrate`
-- `read_deep`
-- `read_details`
-- `save_memory`
-- `validate`
-- `inspect`
-- `append_detail`
-- `update_deep`
-- `update_index`
-- `propose_compaction`
-
-The broad tool shape keeps host approval UX simple. The `save_memory` action bundles the full write chain: append L3 detail, update relevant L2 files, update L1 quick memory, then validate topology.
-
-Manual MCP config:
-
-```json
-{
-  "mcpServers": {
-    "contextline": {
-      "command": "contextline-mcp",
-      "args": [],
-      "env": {
-        "CONTEXTLINE_ROOT": "/path/to/project/.contextline"
-      }
-    }
-  }
-}
-```
-
-## Privacy
-
-ContextLine stores memory in local files under the folder you choose. It does not upload memory or run semantic extraction inside the server. The host assistant decides what to save and calls the local MCP tool.
-
-## Development
-
-```sh
-npm install
-npm run build
-npm test
-```
-
-To test the CLI locally:
-
-```sh
-npm link
-contextline setup
-```
-
-If auto-detection fails, or if you want a different memory folder:
-
-```sh
-contextline setup --host codex --root .contextline
-```
-
-To inspect the npm package contents before publishing:
-
-```sh
-npm pack --dry-run
-```
-
-## Publishing
-
-Before publishing:
-
-```sh
-npm run build
-npm test
-npm pack --dry-run
-```
-
-Then publish:
-
-```sh
-npm publish --access public
-git tag v0.1.0
-git push origin main --tags
-```
-
-## Limitations
-
-V1 intentionally excludes embeddings, vector search, cloud sync, databases, GUI, telemetry upload, team sharing, and automatic semantic classification inside the server.
-
-Currently supported host setup is Codex. Other MCP-capable hosts can use manual MCP configuration.
+# ContextLine
+
+ContextLine is a local-first, filesystem-backed memory layer for AI assistants.
+
+It gives an assistant a small quick-memory file, links into deeper Markdown memory files, and checkpoint instructions for saving durable memory. The host model decides what is worth remembering and writes normal Markdown files.
+
+For product context and examples, see [Why ContextLine Exists](docs/why-contextline.md).
+
+## Install
+
+```sh
+npm install -g @contextline/contextline
+contextline setup
+```
+
+The install step prints a reminder to run `contextline setup`. Setup is explicit because it creates local memory files and host integration config.
+
+## Quick Start With Codex Or Claude Code
+
+From the project where you want memory enabled:
+
+```sh
+contextline setup
+codex
+# or
+claude
+```
+
+By default, setup stores memory in `./.contextline`, detects supported hosts, and configures Codex and Claude Code when available.
+
+Setup creates:
+
+- `.contextline/` for local memory
+- `.codex/hooks.json` for the Codex `SessionStart` and `UserPromptSubmit` hooks
+- `.codex/hooks/contextline-hook.mjs` for the hook command
+- `.codex/config.toml` for a filesystem MCP server scoped to `.contextline/`
+- `.claude/settings.json` for the Claude Code `SessionStart` and `UserPromptSubmit` hooks
+- `.claude/hooks/contextline-hook.mjs` for the hook command
+
+On session start, the host gets a bounded memory snapshot from `L1_Quick.md`. On each user prompt, the host gets a checkpoint instruction to save durable memory from the previous exchange when the exchange was not purely transient.
+
+## What Gets Stored
+
+ContextLine writes plain Markdown:
+
+```text
+.contextline/
+  L1_Quick.md
+  L2_Deep/
+    person_customer.md
+    project_contextline.md
+    area_work.md
+    preference_media.md
+  maintenance/
+    proposals/
+  contextline_instructions.md
+  config.json
+```
+
+The cache model is:
+
+- `L1_Quick.md`: compact facts, summaries, and active pointers.
+- `L2_Deep/`: dated durable memory files per important person, object, project, place, preference area, event, or decision thread. L2 entries include the relevant discussion context directly.
+
+V1 uses flat L2 filenames with semantic prefixes, such as `person_`, `project_`, `area_`, `place_`, `preference_`, `decision_`, `event_`, and `org_`.
+
+Topology rules:
+
+- L1 may link only to L2 files.
+- L1 memory lines should link to relevant L2 files.
+- L2 memory lines should be dated and should generally not contain wiki links.
+
+## CLI
+
+```sh
+contextline setup [--host codex|claude|claude-code|auto|none] [--root .contextline]
+contextline hook --root <root>
+```
+
+## Host Integration
+
+ContextLine does not run a custom MCP server. It installs hooks that provide the assistant with:
+
+- session-start memory hydration from `L1_Quick.md`
+- per-prompt checkpoint instructions for saving durable memory
+- a local `.contextline/` file structure
+
+Codex setup also registers `@modelcontextprotocol/server-filesystem`, scoped only to the `.contextline/` folder, so Codex can use file tools for memory reads and writes. Claude Code uses its native file tools plus project permissions for `.contextline/**`.
+
+Manual Codex filesystem MCP config:
+
+```toml
+[mcp_servers.filesystem]
+type = "stdio"
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project/.contextline"]
+startup_timeout_sec = 10
+tool_timeout_sec = 10
+```
+
+## Privacy
+
+ContextLine stores memory in local files under the folder you choose. It does not upload memory or run semantic extraction in a server. The host assistant decides what to save and edits the local Markdown files.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test
+```
+
+To test the CLI locally:
+
+```sh
+npm install -g .
+contextline setup
+```
+
+If auto-detection fails, or if you want a different memory folder:
+
+```sh
+contextline setup --host claude --root .contextline
+```
+
+To inspect the npm package contents before publishing:
+
+```sh
+npm pack --dry-run
+```
+
+## Publishing
+
+Before publishing:
+
+```sh
+npm run build
+npm test
+npm pack --dry-run
+```
+
+Then publish:
+
+```sh
+npm publish --access public
+git tag v0.2.0
+git push origin main --tags
+```
+
+## Limitations
+
+V1 intentionally excludes embeddings, vector search, cloud sync, databases, GUI, telemetry upload, team sharing, and automatic semantic classification.
+
+Currently supported host setup is Codex and Claude Code.