@fingerskier/augment 0.1.0

package/docs/FEATURES.md

@@ -0,0 +1,245 @@
+# 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.

package/integrations/claude/CLAUDE.md

@@ -0,0 +1,28 @@
+# 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.

package/integrations/codex/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: augment-context
+description: Use Augment MCP memories to gather and persist project context during coding sessions.
+---
+
+# Augment Context
+
+Use this skill when working in a repository with the Augment MCP server available.
+
+## Workflow
+
+1. At session start, call `init_project`.
+2. Search for context using a concise task summary.
+3. Before substantial edits, search again for the specific file, component, or behavior.
+4. Persist durable findings with `upsert`:
+   - `SPEC` for requirements and contracts.
+   - `ARCH` for design decisions.
+   - `TODO` for planned work.
+   - `ISSUE` for bugs, risks, and blockers.
+   - `WORK` for concise implementation notes.
+5. Link related memories when the relationship is clear.
+6. At finish, write a short `WORK` memory describing what changed and how it was verified.
+
+## Guardrails
+- Do not store secrets, credentials, tokens, or private keys.
+- Do not store huge logs, dependency dumps, generated files, or full source files.
+- Keep each memory focused; split large notes before calling `upsert`.
+- Treat numeric memory IDs as local handles. Relative paths are the durable identity.
+- Use returned search text directly as context; do not ask Augment to summarize.

package/integrations/examples/claude-mcp-config.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "augment": {
+      "command": "npm",
+      "args": ["exec", "--yes", "--package", "@fingerskier/augment", "--", "augment-mcp"],
+      "env": {
+        "AUGMENT_MEMORY_ROOT": "C:\\Users\\you\\Dropbox\\augment-memories"
+      }
+    }
+  }
+}

package/integrations/examples/codex-mcp-config.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "augment": {
+      "command": "npm",
+      "args": ["exec", "--yes", "--package", "@fingerskier/augment", "--", "augment-mcp"],
+      "env": {
+        "AUGMENT_MEMORY_ROOT": "C:\\Users\\you\\Dropbox\\augment-memories"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@fingerskier/augment",
+  "version": "0.1.0",
+  "description": "Local RAG memory system for coding agents",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "augment": "./dist/bin/augment.js",
+    "augment-daemon": "./dist/bin/augment-daemon.js",
+    "augment-mcp": "./dist/bin/augment-mcp.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "integrations",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --import tsx --test \"test/**/*.test.ts\"",
+    "check": "npm run build && npm test",
+    "prepack": "npm run check",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.0",
+    "@libsql/client": "^0.15.15",
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "chokidar": "^4.0.3",
+    "gray-matter": "^4.0.3",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "Apache-2.0"
+}