@fingerskier/augment 0.1.0 → 0.1.3

package/docs/FEATURES.md

@@ -1,245 +1,277 @@
-# Augment Features
-
-Augment is a local RAG memory system for coding agents.
-
-## Memory Folder
-
-- The memory folder is a normal directory.
-- Only one memory root is configured per local system.
-- Memory file paths are relative to this root.
-
-## Memories
-
-- Memories are text files in the memory folder.
-- Files are markdown with YAML frontmatter.
-- Canonical organization:
-
-```txt
-org/repo/kind/name.md
-```
-
-- Supported MVP kinds:
-  - `ISSUE`
-  - `ARCH`
-  - `TODO`
-  - `SPEC`
-  - `WORK`
-
-Memory files are the canonical source of truth. Numeric memory IDs are local
-database IDs only and are not written to memory files. Relative paths are the
-durable cross-system identity.
-
-Example:
-
-```md
----
-kind: ARCH
-project: fingerskier/augment
-name: search-contract
-tags: [mcp, search, ranking]
-links:
-  - to: fingerskier/augment/SPEC/local-daemon.md
-    type: RELATED
-created_at: 2026-06-29T00:00:00Z
-updated_at: 2026-06-29T00:00:00Z
----
-
-Body text.
-```
-
-## Database
-
-- A shared local daemon watches memory files and maintains a rebuildable libsql
-  index.
-- The database includes metadata, body text, embeddings, gzip density score, and
-  derived link rows.
-- `Xenova/bge-small-en-v1.5` via `@huggingface/transformers` provides 384D
-  embeddings.
-- The database file is rebuildable and should not be synced as canonical state.
-
-Tables:
-
-- `projects`
-  - `id`
-  - `name`
-  - `org`
-  - `repo`
-  - `source`
-- `memories`
-  - `id`
-  - `project_id`
-  - `kind`
-  - `name`
-  - `relative_path`
-  - `content_hash`
-  - `frontmatter_hash`
-  - `size`
-  - `density`
-  - `mtime`
-- `memory_embeddings`
-  - `memory_id`
-  - `model_id`
-  - `model_version`
-  - `dimensions`
-  - `vector`
-  - `embedded_hash`
-- `links`
-  - `id`
-  - `from_memory_id`
-  - `to_memory_id`
-  - `type`
-
-Links are written to the source memory's frontmatter using target relative paths.
-The daemon rebuilds local `links` rows from those declarations.
-
-## Daemon
-
-- `augment-daemon` is shared by all local MCP servers for one memory root.
-- The daemon owns file watching, embedding, and database writes.
-- It exposes a localhost HTTP control endpoint.
-- It binds to `127.0.0.1`, uses a dynamic port by default, writes a discovery
-  file, and requires a generated auth token for non-health requests.
-
-## MCP Tools
-
-### `init_project`
-
-Infers or accepts a project name and upserts a project record.
-
-Inputs:
-
-```ts
-{ project_name?: string }
-```
-
-### `list_projects`
-
-Lists known project records.
-
-Inputs:
-
-```ts
-{ name?: string }
-```
-
-### `search`
-
-Recalls memories semantically and lexically similar to a query.
-
-Inputs:
-
-```ts
-{
-  project_name?: string;
-  query: string;
-  limit?: number;
-  max_chars?: number;
-  kinds?: Array<"ISSUE" | "ARCH" | "TODO" | "SPEC" | "WORK">;
-  include_linked?: boolean;
-}
-```
-
-Behavior:
-
-- Returns plain text suitable for direct context injection.
-- Includes local memory IDs, project names, paths, kinds, scores, and link
-  annotations.
-- May use the CWD project as a modest metadata boost, but cross-project results
-  are allowed based on score.
-- Prioritizes linked memories without requiring them.
-- Does not summarize or extract arbitrary excerpts.
-
-### `upsert`
-
-Stores text in a memory file.
-
-Inputs:
-
-```ts
-{
-  project_id: number;
-  memory_id?: number;
-  kind?: "ISSUE" | "ARCH" | "TODO" | "SPEC" | "WORK";
-  name: string;
-  content: string;
-  tags?: string[];
-}
-```
-
-If `memory_id` is absent, Augment may automatically update a highly similar
-memory in the same project and kind.
-
-### `read`
-
-Reads one memory by local numeric ID.
-
-Inputs:
-
-```ts
-{ id: number }
-```
-
-### `link`
-
-Creates a directional link between local memory IDs and persists it as a
-relative-path link in the source memory frontmatter.
-
-Inputs:
-
-```ts
-{
-  from_memory_id: number;
-  to_memory_id: number;
-  type?: "DEPENDS_ON" | "BLOCKS" | "IMPLEMENTS" | "PARENT" | "RELATED";
-}
-```
-
-### `list_links`
-
-Lists inbound and outbound links involving a memory.
-
-Inputs:
-
-```ts
-{ memory_id: number }
-```
-
-### `unlink`
-
-Removes a link by local link ID.
-
-Inputs:
-
-```ts
-{ id: number }
-```
-
-## Configuration
-
-Resolution order:
-
-1. Environment variables.
-2. `~/.augment/config.json`.
-3. Defaults.
-
-Environment variables:
-
-- `AUGMENT_MEMORY_ROOT`
-- `AUGMENT_STATE_DIR`
-- `AUGMENT_DAEMON_PORT`
-
-Defaults:
-
-- Memory root: `~/.augment/memories`
-- State directory: `~/.augment/state`
-- Database: `~/.augment/state/index.db`
-- Daemon discovery file: `~/.augment/state/daemon.json`
-
-## Deferred
-
-- Dashboard.
-- `sleep`.
-- `dream`.
-- Remote sync.
-- Memory `move`.
-- CLI aliases and UX beyond diagnostics/config helpers.
+# Augment Features
+
+Augment is a local RAG memory system for coding agents.
+
+## Memory Folder
+
+- The memory folder is a normal directory.
+- Only one memory root is configured per local system.
+- Memory file paths are relative to this root.
+
+## Memories
+
+- Memories are text files in the memory folder.
+- Files are markdown with YAML frontmatter.
+- Canonical organization:
+
+```txt
+org/repo/kind/name.md
+```
+
+- Supported MVP kinds:
+  - `ISSUE`
+  - `ARCH`
+  - `TODO`
+  - `SPEC`
+  - `WORK`
+
+Memory files are the canonical source of truth. Numeric memory IDs are local
+database IDs only and are not written to memory files. Relative paths are the
+durable cross-system identity.
+
+Example:
+
+```md
+---
+kind: ARCH
+project: fingerskier/augment
+name: search-contract
+tags: [mcp, search, ranking]
+links:
+  - to: fingerskier/augment/SPEC/local-daemon.md
+    type: RELATED
+created_at: 2026-06-29T00:00:00Z
+updated_at: 2026-06-29T00:00:00Z
+---
+
+Body text.
+```
+
+## Database
+
+- A shared local daemon watches memory files and maintains a rebuildable libsql
+  index.
+- The database includes metadata, body text, embeddings, gzip density score, and
+  derived link rows.
+- `Xenova/bge-small-en-v1.5` via `@huggingface/transformers` provides 384D
+  embeddings.
+- The database file is rebuildable and should not be synced as canonical state.
+
+Tables:
+
+- `projects`
+  - `id`
+  - `name`
+  - `org`
+  - `repo`
+  - `source`
+- `memories`
+  - `id`
+  - `project_id`
+  - `kind`
+  - `name`
+  - `relative_path`
+  - `content_hash`
+  - `frontmatter_hash`
+  - `size`
+  - `density`
+  - `mtime`
+- `memory_embeddings`
+  - `memory_id`
+  - `model_id`
+  - `model_version`
+  - `dimensions`
+  - `vector`
+  - `embedded_hash`
+- `links`
+  - `id`
+  - `from_memory_id`
+  - `to_memory_id`
+  - `type`
+
+Links are written to the source memory's frontmatter using target relative paths.
+The daemon rebuilds local `links` rows from those declarations.
+
+## Daemon
+
+- `augment-daemon` is shared by all local MCP servers for one memory root.
+- The daemon owns file watching, embedding, and database writes.
+- It exposes a localhost HTTP control endpoint.
+- It binds to `127.0.0.1`, uses a dynamic port by default, writes a discovery
+  file, and requires a generated auth token for non-health requests.
+
+## MCP Tools
+
+### `init_project`
+
+Infers or accepts a project name and upserts a project record.
+
+Inputs:
+
+```ts
+{ project_name?: string }
+```
+
+### `list_projects`
+
+Lists known project records.
+
+Inputs:
+
+```ts
+{ name?: string }
+```
+
+### `search`
+
+Recalls memories semantically and lexically similar to a query.
+
+Inputs:
+
+```ts
+{
+  project_name?: string;
+  query: string;
+  limit?: number;
+  max_chars?: number;
+  kinds?: Array<"ISSUE" | "ARCH" | "TODO" | "SPEC" | "WORK">;
+  include_linked?: boolean;
+}
+```
+
+Behavior:
+
+- Returns plain text suitable for direct context injection.
+- Includes local memory IDs, project names, paths, kinds, scores, and link
+  annotations.
+- May use the CWD project as a modest metadata boost, but cross-project results
+  are allowed based on score.
+- Prioritizes linked memories without requiring them.
+- Does not summarize or extract arbitrary excerpts.
+
+### `upsert`
+
+Stores text in a memory file.
+
+Inputs:
+
+```ts
+{
+  project_id: number;
+  memory_id?: number;
+  kind?: "ISSUE" | "ARCH" | "TODO" | "SPEC" | "WORK";
+  name: string;
+  content: string;
+  tags?: string[];
+}
+```
+
+If `memory_id` is absent, Augment may automatically update a highly similar
+memory in the same project and kind.
+
+### `read`
+
+Reads one memory by local numeric ID.
+
+Inputs:
+
+```ts
+{ id: number }
+```
+
+### `link`
+
+Creates a directional link between local memory IDs and persists it as a
+relative-path link in the source memory frontmatter.
+
+Inputs:
+
+```ts
+{
+  from_memory_id: number;
+  to_memory_id: number;
+  type?: "DEPENDS_ON" | "BLOCKS" | "IMPLEMENTS" | "PARENT" | "RELATED";
+}
+```
+
+### `list_links`
+
+Lists inbound and outbound links involving a memory.
+
+Inputs:
+
+```ts
+{ memory_id: number }
+```
+
+### `unlink`
+
+Removes a link by local link ID.
+
+Inputs:
+
+```ts
+{ id: number }
+```
+
+## Configuration
+
+Resolution order:
+
+1. Environment variables.
+2. `~/.augment/config.json`.
+3. Defaults.
+
+Environment variables:
+
+- `AUGMENT_MEMORY_ROOT`
+- `AUGMENT_STATE_DIR`
+- `AUGMENT_DAEMON_PORT`
+
+Defaults:
+
+- Memory root: `~/.augment/memories`
+- State directory: `~/.augment/state`
+- Database: `~/.augment/state/index.db`
+- Daemon discovery file: `~/.augment/state/daemon.json`
+
+## Agent Integration Installer
+
+The `augment` CLI can install dogfooding integrations:
+
+```powershell
+npm exec --yes --package @fingerskier/augment -- augment install codex --scope user --memory-root "C:\Users\you\Dropbox\augment-memories"
+npm exec --yes --package @fingerskier/augment -- augment install codex --scope repo
+npm exec --yes --package @fingerskier/augment -- augment install claude --scope repo
+npm exec --yes --package @fingerskier/augment -- augment install all --scope user --dry-run
+```
+
+Codex install creates or updates:
+
+- A local plugin folder named `augment`.
+- `.codex-plugin/plugin.json`.
+- `.mcp.json` pointing to the published `@fingerskier/augment` package through
+  an isolated npm `--prefix` directory.
+- `skills/augment-context/SKILL.md`.
+- A personal or repo marketplace entry.
+
+Claude install creates or updates:
+
+- A real Claude Code plugin folder named `augment` with
+  `.claude-plugin/plugin.json`, an auto-discovered `skills/augment-context/SKILL.md`,
+  and a bundled `.mcp.json` (same cwd-safe MCP command shape as Codex).
+- A `.claude-plugin/marketplace.json` entry so the plugin is installable via
+  `/plugin marketplace add` + `/plugin install augment@<marketplace>`.
+- A direct MCP registration so the server is active immediately: repo scope writes
+  `<repo>/.mcp.json`; user scope merges `mcpServers.augment` into `~/.claude.json`,
+  preserving all other keys.
+- A marked Augment block in `CLAUDE.md` carrying the always-on memory workflow.
+
+## Deferred
+
+- Dashboard.
+- `sleep`.
+- `dream`.
+- Remote sync.
+- Memory `move`.
+- CLI aliases and UX beyond diagnostics/config helpers.

package/integrations/claude/CLAUDE.md

@@ -1,28 +1,56 @@
-# Augment Memory Workflow
-
-When the Augment MCP server is configured, use it as the local project memory.
-
-Session start:
-- Call `init_project`.
-- Call `search` with the user's task summary.
-
-Before implementation:
-- Search for the specific file, subsystem, behavior, or error.
-- Read exact memories by ID when search results point to important context.
-
-During and after work:
-
-- Use `upsert` for durable notes:
-  - `SPEC` for requirements and contracts.
-  - `ARCH` for decisions and design rationale.
-  - `TODO` for future work.
-  - `ISSUE` for bugs, risks, and blockers.
-  - `WORK` for concise implementation notes.
-- Use `link` when one memory depends on, implements, blocks, parents, or relates to another.
-- At completion, write a short `WORK` memory with the outcome and verification.
-
-Rules:
-- Do not store secrets or credentials.
-- Do not store large logs, generated files, dependency dumps, or full source files.
-- Keep memories small and focused.
-- Numeric memory IDs are local to the machine. Relative paths are durable across systems.
+# Augment Memory Workflow
+
+When the Augment MCP server is configured, use it as the local project memory.
+
+## Session Start
+
+- Call `init_project`.
+- Call `search` with the user's task summary.
+- Read exact memories when search results identify governing context.
+
+## Before Implementation
+
+- Search for the specific file, subsystem, behavior, command, or error.
+- If the work depends on a prior decision, read and follow the relevant `SPEC`
+  or `ARCH` memory.
+- If no relevant memory exists but the task creates a durable requirement or
+  decision, create one before implementation.
+
+## Memory Triggers
+
+Call `upsert` whenever one of these durable events happens:
+
+- A requirement, API contract, data model, or tool contract is clarified:
+  use `SPEC`.
+- An implementation approach, tradeoff, transport choice, persistence model, or
+  architecture decision is made: use `ARCH`.
+- A bug, risk, failing behavior, or blocker is discovered: use `ISSUE`.
+- Follow-up work is intentionally deferred: use `TODO`.
+- A meaningful implementation milestone is completed: use `WORK`.
+- A test scenario, regression case, or verification rule is learned: use `SPEC`
+  or `WORK`, whichever is more durable.
+
+## Links
+
+After creating or updating a memory:
+
+- Use `link` when one memory depends on, implements, blocks, parents, or relates
+  to another.
+- Prefer linking new `WORK` notes to the `SPEC`, `ARCH`, `ISSUE`, or `TODO` they
+  address.
+
+## Completion
+
+- Upsert a concise `WORK` memory with what changed, key files, and verification.
+- Upsert or update `TODO` memories for known remaining work.
+- Link the final `WORK` memory to the relevant planning/decision memories.
+
+## Rules
+
+- Do not store secrets, credentials, tokens, or private keys.
+- Do not store large logs, generated files, dependency dumps, or full source files.
+- Keep memories small and focused.
+- Use returned search text directly as context; do not ask Augment to summarize.
+- Numeric memory IDs are local to the machine. Relative paths are durable across systems.
+- Do not create memories for trivial edits, transient exploration, or facts that
+  are already obvious from the current diff.