kiro-memory 1.0.0

package/README.md

@@ -0,0 +1,290 @@
+# ContextKit
+
+**Persistent cross-session memory for [Kiro CLI](https://kiro.dev/).**
+
+![CI](https://github.com/auriti-web-design/contextkit/actions/workflows/ci.yml/badge.svg)
+![npm](https://img.shields.io/npm/v/contextkit)
+![License](https://img.shields.io/badge/license-AGPL--3.0-blue)
+![Node](https://img.shields.io/badge/node-%3E%3D18-green)
+
+---
+
+ContextKit gives your Kiro agent memory that persists across sessions. It automatically captures what happened -- files changed, tools used, decisions made -- and feeds relevant context back at the start of the next session. No manual bookkeeping. Your agent picks up exactly where it left off.
+
+## What Your Agent Sees
+
+When a new session starts, ContextKit automatically injects previous session context:
+
+```
+# ContextKit: Previous Session Context
+
+## Previous Sessions
+
+- **Learned**: JWT tokens need refresh logic with 5-minute buffer
+- **Completed**: Implemented OAuth2 login flow with Google provider
+- **Next steps**: Files modified: src/auth/oauth.ts, src/middleware/auth.ts
+
+## Recent Observations
+
+- **[file-write] Written: src/auth/oauth.ts**: Implemented Google OAuth2 provider
+- **[command] Executed: npm test -- --coverage**: All 47 tests passing
+- **[research] Searched: JWT refresh token best practices**: Found rotating refresh pattern
+
+> Project: my-app | Observations: 23 | Summaries: 5
+```
+
+## Features
+
+- **Automatic Context Injection** -- Previous session knowledge injected at agent start via `agentSpawn` hook
+- **Prompt Tracking** -- Every user prompt recorded for continuity (`userPromptSubmit` hook)
+- **Tool & File Monitoring** -- File writes, command executions, and tool usage captured in real time (`postToolUse` hook)
+- **Session Summaries** -- Structured summaries generated when sessions end (`stop` hook)
+- **MCP Server** -- 4 tools (`search`, `timeline`, `get_observations`, `get_context`) exposed via Model Context Protocol
+- **Full-Text Search** -- SQLite FTS5 for fast, typo-tolerant search across all stored context
+- **TypeScript SDK** -- Programmatic access to the entire memory system
+- **CLI** -- Query and manage context directly from the terminal
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g contextkit
+
+# Install into Kiro CLI (hooks + MCP server + agent config)
+contextkit install
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/auriti-web-design/contextkit.git
+cd contextkit
+npm install && npm run build
+npm run install:kiro
+```
+
+Start the worker, then use Kiro as usual -- ContextKit runs in the background:
+
+```bash
+npm run worker:start
+```
+
+## Kiro Integration
+
+ContextKit registers **4 hooks** and an **MCP server** with Kiro CLI. The agent configuration is installed to `~/.kiro/agents/contextkit.json`:
+
+```json
+{
+  "name": "contextkit-memory",
+  "tools": ["read", "write", "shell", "glob", "grep", "@contextkit"],
+  "mcpServers": {
+    "contextkit": {
+      "command": "node",
+      "args": ["/path/to/dist/servers/mcp-server.js"]
+    }
+  },
+  "hooks": {
+    "agentSpawn": [{ "command": "node /path/to/dist/hooks/agentSpawn.js" }],
+    "userPromptSubmit": [{ "command": "node /path/to/dist/hooks/userPromptSubmit.js" }],
+    "postToolUse": [{ "command": "node /path/to/dist/hooks/postToolUse.js", "matcher": "*" }],
+    "stop": [{ "command": "node /path/to/dist/hooks/stop.js" }]
+  }
+}
+```
+
+The hooks are fully automatic. No changes to your workflow required.
+
+## Architecture
+
+```
+                     Kiro CLI
+                        |
+          +-------------+-------------+
+          |             |             |
+     agentSpawn   postToolUse      stop
+   (inject ctx)  (track tools)  (summarize)
+          |             |             |
+          +------+------+------+------+
+                 |             |
+            Worker HTTP    MCP Server
+            (port 3001)     (stdio)
+                 |             |
+                 +------+------+
+                        |
+                   SQLite + FTS5
+               (~/.contextkit/contextkit.db)
+```
+
+### Hooks
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `agentSpawn` | Session starts | Injects relevant context from previous sessions |
+| `userPromptSubmit` | User sends prompt | Records the prompt for session continuity |
+| `postToolUse` | Any tool completes | Captures file writes, commands, research actions |
+| `stop` | Session ends | Generates and stores a structured session summary |
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `search` | Full-text search across observations and summaries. Supports project and type filters. |
+| `timeline` | Chronological context around a specific observation. Shows what happened before and after. |
+| `get_observations` | Retrieve full details of specific observations by ID. Use after `search` to drill down. |
+| `get_context` | Get recent observations, summaries, and prompts for a project. |
+
+### Storage
+
+| Component | Location |
+|-----------|----------|
+| Database | `~/.contextkit/contextkit.db` |
+| Logs | `~/.contextkit/logs/` |
+| Archives | `~/.contextkit/archives/` |
+| Backups | `~/.contextkit/backups/` |
+
+## SDK
+
+The TypeScript SDK provides full programmatic access to the memory system.
+
+```typescript
+import { createContextKit } from 'contextkit';
+
+const ctx = createContextKit({ project: 'my-project' });
+
+// Retrieve context for the current project
+const context = await ctx.getContext();
+console.log(context.relevantObservations);
+console.log(context.relevantSummaries);
+
+// Store an observation
+await ctx.storeObservation({
+  type: 'note',
+  title: 'Auth fix',
+  content: 'Fixed OAuth flow -- tokens now refresh with 5-min buffer'
+});
+
+// Full-text search with filters
+const results = await ctx.searchAdvanced('authentication', {
+  type: 'file-write',
+  limit: 10
+});
+
+// Get chronological timeline around an observation
+const timeline = await ctx.getTimeline(42, 5, 5);
+
+// Store a session summary
+await ctx.storeSummary({
+  request: 'Implement OAuth2 login',
+  learned: 'Google OAuth requires PKCE for SPAs',
+  completed: 'Login flow with Google provider',
+  nextSteps: 'Add refresh token rotation'
+});
+
+// Always close when done
+ctx.close();
+```
+
+### SDK API Reference
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getContext()` | `ContextContext` | Recent observations, summaries, and prompts for the project |
+| `storeObservation(data)` | `number` | Store an observation, returns its ID |
+| `storeSummary(data)` | `number` | Store a session summary, returns its ID |
+| `search(query)` | `{ observations, summaries }` | Basic full-text search |
+| `searchAdvanced(query, filters)` | `{ observations, summaries }` | FTS5 search with project/type/date/limit filters |
+| `getTimeline(anchorId, before, after)` | `TimelineEntry[]` | Chronological context around an observation |
+| `getRecentObservations(limit)` | `Observation[]` | Most recent observations |
+| `getRecentSummaries(limit)` | `Summary[]` | Most recent summaries |
+| `getOrCreateSession(id)` | `DBSession` | Get or initialize a session |
+| `storePrompt(sessionId, num, text)` | `number` | Store a user prompt |
+| `close()` | `void` | Close the database connection |
+
+## CLI Reference
+
+```bash
+contextkit <command> [options]
+```
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `contextkit context` | `ctx` | Display current project context |
+| `contextkit search <query>` | -- | Search across all stored context |
+| `contextkit observations [limit]` | `obs` | Show recent observations (default: 10) |
+| `contextkit summaries [limit]` | `sum` | Show recent summaries (default: 5) |
+| `contextkit add-observation <title> <content>` | `add-obs` | Manually add an observation |
+| `contextkit add-summary <content>` | `add-sum` | Manually add a summary |
+
+### Examples
+
+```bash
+# View what ContextKit knows about your project
+contextkit context
+
+# Search for past work on authentication
+contextkit search "OAuth token refresh"
+
+# Show the last 20 observations
+contextkit observations 20
+
+# Manually record a decision
+contextkit add-observation "Architecture Decision" "Chose PostgreSQL over MongoDB for ACID compliance"
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTEXTKIT_DATA_DIR` | `~/.contextkit` | Base directory for all ContextKit data |
+| `CONTEXTKIT_WORKER_HOST` | `127.0.0.1` | Worker service bind address |
+| `CONTEXTKIT_WORKER_PORT` | `3001` | Worker service port |
+| `CONTEXTKIT_LOG_LEVEL` | `INFO` | Log verbosity: `DEBUG`, `INFO`, `WARN`, `ERROR` |
+| `KIRO_CONFIG_DIR` | `~/.kiro` | Kiro CLI configuration directory |
+
+### Worker Management
+
+```bash
+npm run worker:start     # Start the background worker
+npm run worker:stop      # Stop the worker
+npm run worker:restart   # Restart after code changes
+npm run worker:status    # Check if worker is running
+npm run worker:logs      # View recent logs
+```
+
+## Requirements
+
+- **Node.js** >= 18
+- **Kiro CLI** -- [kiro.dev](https://kiro.dev/)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build and sync to Kiro
+npm run dev
+
+# Run tests
+npm test
+
+# Run specific test suites
+npm run test:sqlite
+npm run test:search
+npm run test:context
+npm run test:server
+```
+
+## Contributing
+
+Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.html)
+
+---
+
+Built by [auriti-web-design](https://github.com/auriti-web-design)

package/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "kiro-memory",
+  "version": "1.0.0",
+  "description": "Persistent cross-session memory for Kiro CLI. Automatically tracks context, observations, and summaries across coding sessions.",
+  "keywords": [
+    "kiro",
+    "kiro-cli",
+    "context",
+    "memory",
+    "persistence",
+    "mcp",
+    "hooks",
+    "sqlite",
+    "typescript",
+    "agent",
+    "ai-tools"
+  ],
+  "author": "auriti-web-design",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/auriti-web-design/contextkit.git"
+  },
+  "homepage": "https://github.com/auriti-web-design/contextkit#readme",
+  "bugs": {
+    "url": "https://github.com/auriti-web-design/contextkit/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sdk": {
+      "types": "./dist/sdk/index.d.ts",
+      "import": "./dist/sdk/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "plugin"
+  ],
+  "bin": {
+    "contextkit": "./dist/cli/contextkit.js"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "dev": "npm run build-and-sync",
+    "build": "node scripts/build-plugin.js",
+    "build-and-sync": "npm run build && npm run sync-kiro && npm run worker:restart",
+    "sync-kiro": "node scripts/sync-kiro.cjs",
+    "sync-kiro:force": "node scripts/sync-kiro.cjs --force",
+    "worker:start": "bun plugin/scripts/worker-service.cjs start",
+    "worker:stop": "bun plugin/scripts/worker-service.cjs stop",
+    "worker:restart": "bun plugin/scripts/worker-service.cjs restart",
+    "worker:status": "bun plugin/scripts/worker-service.cjs status",
+    "worker:logs": "tail -n 50 ~/.contextkit/logs/worker-$(date +%Y-%m-%d).log",
+    "worker:tail": "tail -f 50 ~/.contextkit/logs/worker-$(date +%Y-%m-%d).log",
+    "queue": "bun scripts/check-pending-queue.ts",
+    "queue:process": "bun scripts/check-pending-queue.ts --process",
+    "queue:clear": "bun scripts/clear-failed-queue.ts --all --force",
+    "context:regenerate": "bun scripts/regenerate-context.ts",
+    "context:dry-run": "bun scripts/regenerate-context.ts --dry-run",
+    "test": "bun test",
+    "test:sqlite": "bun test tests/sqlite/",
+    "test:agents": "bun test tests/worker/agents/",
+    "test:search": "bun test tests/worker/search/",
+    "test:context": "bun test tests/context/",
+    "test:infra": "bun test tests/infrastructure/",
+    "test:server": "bun test tests/server/",
+    "install:kiro": "bash scripts/install-kiro.sh",
+    "prepublishOnly": "npm run build",
+    "release": "np",
+    "release:patch": "np patch --no-cleanup",
+    "release:minor": "np minor --no-cleanup",
+    "release:major": "np major --no-cleanup"
+  },
+  "np": {
+    "yarn": false,
+    "contents": ".",
+    "testScript": "test",
+    "2fa": false
+  },
+  "dependencies": {
+    "@chroma-core/default-embed": "^0.1.9",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ansi-to-html": "^0.7.2",
+    "better-sqlite3": "^12.6.2",
+    "chromadb": "^3.2.2",
+    "cors": "^2.8.5",
+    "dompurify": "^3.3.1",
+    "express": "^4.18.2",
+    "glob": "^11.0.3",
+    "handlebars": "^4.7.8",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "yaml": "^2.8.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/cors": "^2.8.19",
+    "@types/dompurify": "^3.0.5",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.5",
+    "@types/react-dom": "^18.3.0",
+    "bun-types": "^1.0.0",
+    "esbuild": "^0.27.2",
+    "np": "^11.0.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.3.0"
+  }
+}