v1.0.0: initial release

MCP server that gives AI agents persistent memory across sessions.
Git-synced knowledge base with semantic search over session history.
Auto-distills session insights and scrubs secrets before pushing to git.

Author: keshrath

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm run typecheck
+      - run: npm run lint
+      - run: npm run format:check
+      - run: npm test
+
+  publish:
+    needs: check
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+*.db
+*.db-wal
+*.db-shm
+.env
+.env.local
+coverage/
+*.tgz
+*.tsbuildinfo
+.DS_Store
+Thumbs.db
+.worktrees/
+.claude/worktrees/

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

.npmrc

@@ -0,0 +1 @@
+registry=https://registry.npmjs.org/

CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## 1.0.0 (2026-03-26)
+
+Initial release.
+
+### MCP Tools (12)
+
+**Knowledge (5):** `knowledge_list`, `knowledge_read`, `knowledge_write`, `knowledge_delete`, `knowledge_sync`
+
+**Sessions (5):** `knowledge_sessions`, `knowledge_search`, `knowledge_get`, `knowledge_summary`, `knowledge_recall`
+
+**Admin (2):** `knowledge_index_status`, `knowledge_config`
+
+### Search Engine
+
+- Hybrid semantic + TF-IDF search with configurable alpha blending
+- Recency decay weighting (newer sessions rank higher)
+- Fuzzy matching via Levenshtein distance
+- 6 recall scopes: errors, plans, configs, tools, files, decisions
+- Role-based filtering (all, user, assistant)
+- Regex mode for pattern-based searches
+
+### Embeddings & Vector Store
+
+- SQLite vector store with sqlite-vec for cosine similarity
+- 4 embedding providers: local (Hugging Face), OpenAI, Claude/Voyage, Gemini
+- Background indexer runs on server startup
+- Automatic provider switching with dimension migration
+
+### Knowledge Base
+
+- Git-synced markdown vault at `~/claude-memory/`
+- 5 categories: projects, people, decisions, workflows, notes
+- YAML frontmatter for metadata (title, tags, updated)
+- Auto git commit + push on writes, pull on reads
+- Configurable git URL via `knowledge_config` tool or `KNOWLEDGE_GIT_URL` env var
+- New repos auto-scaffolded with README, .gitignore, and category dirs
+
+### Auto-Distillation
+
+- Automatic extraction of session insights into knowledge base
+- Project name normalization (worktrees, swarms merged into parent)
+- Secrets scrubbing: API keys, tokens, passwords, JWTs, private keys redacted
+- System noise stripped (XML tags, task notifications)
+- Absolute paths normalized to `~/`
+- Defense-in-depth audit blocks writes with surviving sensitive content
+
+### Persistent Configuration
+
+- `knowledge_config` tool for runtime setup (no restart needed)
+- Config stored at XDG/AppData location (tool-agnostic)
+- Priority: env vars > persisted config > defaults
+
+### Web Dashboard
+
+- http://localhost:3423, auto-starts with MCP server
+- 5 tabs: Knowledge, Search, Sessions, Recall, Embeddings
+- MD3 design language matching agent-comm and agent-tasks
+- Light/dark theme with localStorage persistence
+- Side panel (560px, resizable) with markdown rendering
+- Live reload via file watcher + WebSocket
+- Semantic search toggle with score breakdown
+
+### Performance
+
+- Session file mtime cache (re-parses only changed files)
+- Global TF-IDF index cache with 60s TTL
+- Background embedding indexer (non-blocking)
+
+### Infrastructure
+
+- REST API: 10 endpoints (knowledge, sessions, search, recall, index-status, health)
+- WebSocket server for real-time dashboard updates
+- 280 tests passing (vitest)
+- TypeScript strict mode, ES modules
+- GitHub Actions CI (Node 20/22 matrix, npm publish on tags)

CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to agent-knowledge
+
+## Getting Started
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/keshrath/agent-knowledge.git
+   cd agent-knowledge
+   ```
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Build:
+   ```bash
+   npm run build
+   ```
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js >= 20** (LTS recommended)
+- **Git** (for knowledge base sync)
+- A knowledge base repo (or create one):
+  ```bash
+  mkdir -p ~/claude-memory && cd ~/claude-memory && git init
+  mkdir projects people decisions workflows notes
+  ```
+
+### Development Mode
+
+```bash
+# Watch mode — recompiles on changes
+npm run dev
+
+# Start dashboard standalone (port 3423)
+KNOWLEDGE_PORT=3423 node dist/dashboard.js
+
+# Run tests
+npm test
+npm run test:watch
+```
+
+### Environment
+
+```bash
+export KNOWLEDGE_MEMORY_DIR=~/claude-memory
+export CLAUDE_DIR=~/.claude
+export KNOWLEDGE_PORT=3423
+```
+
+## Project Structure
+
+```
+agent-knowledge/
+  src/
+    index.ts              Entry point (MCP stdio + dashboard auto-start)
+    server.ts             MCP server, 10 tool definitions, request routing
+    dashboard.ts          HTTP + WebSocket server, REST API, file watcher
+    types.ts              KnowledgeConfig, getConfig()
+    knowledge/
+      store.ts            Markdown CRUD, frontmatter parsing, path traversal protection
+      search.ts           TF-IDF search over knowledge entries with regex fallback
+      git.ts              git pull/push/sync with timeouts
+    sessions/
+      parser.ts           JSONL parsing with mtime-based cache
+      search.ts           TF-IDF ranked search with 60s global index cache
+      scopes.ts           6 search scopes (errors, plans, configs, tools, files, decisions)
+      summary.ts          Session summaries, topic extraction, file path detection
+    search/
+      tfidf.ts            TF-IDF scoring engine (tokenizer, stopwords, index)
+      fuzzy.ts            Levenshtein distance, sliding window fuzzy matching
+      types.ts            SearchResult, SearchOptions interfaces
+    ui/
+      index.html          Dashboard SPA
+      styles.css           MD3 design tokens (light + dark)
+      app.js              Client-side vanilla JS (WebSocket, tabs, rendering)
+  tests/
+    tfidf.test.ts         TF-IDF engine tests (8)
+    fuzzy.test.ts         Fuzzy matching tests (7)
+  docs/
+    SETUP.md              Installation and configuration guide
+    ARCHITECTURE.md       Technical architecture documentation
+    DASHBOARD.md          Dashboard features and usage
+    assets/               Screenshots
+```
+
+## Code Style
+
+- **TypeScript** with strict mode, ES modules
+- **Imports**: use `.js` extensions (TypeScript NodeNext convention)
+- **Naming**: `camelCase` for functions/variables, `PascalCase` for types/classes, `UPPER_SNAKE` for constants
+- **Async**: use `async`/`await` over raw promises
+- **Error handling**: throw descriptive errors, catch and return MCP-formatted errors in tool handlers
+- **No external formatters** -- match existing code style
+
+## Testing
+
+```bash
+npm test                          # Run all tests
+npm run test:watch                # Watch mode
+npx vitest run tests/tfidf.test.ts  # Single file
+npm run lint                      # Type-check (tsc --noEmit)
+```
+
+Tests use **vitest** with `fs.mkdtempSync` for temp directories in filesystem tests.
+
+### What to Test
+
+- Knowledge store: CRUD, frontmatter parsing, category validation, path traversal
+- TF-IDF: tokenization, stopwords, ranking correctness, edge cases
+- Fuzzy: Levenshtein distance, threshold filtering, sliding window
+- Sessions: JSONL parsing, malformed line handling, message extraction
+
+## Pull Requests
+
+1. All tests must pass
+2. Type-check must be clean (`npm run typecheck`)
+3. Lint and format checks must pass (`npm run check`)
+4. Update docs if changing tool behavior or adding features
+5. Keep commits focused -- one logical change per commit
+
+## License
+
+MIT

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keshrath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.