v0.1.0: open-source release

Schema v2 with alias indexing, tag filtering, and fts_sources table.
Four-channel RRF search (BM25 + vector + indegree + title/alias).
Frontmatter parsing for tags and aliases. Tool consolidation 8→6.
CLI mode (search, index, status). Chunk overlap support.
SSE security hardened (default 127.0.0.1). CI with SHA-pinned actions.
217 tests. Python 3.11+. MIT license.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: simon_sun

.github/workflows/test.yml

@@ -0,0 +1,25 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: astral-sh/setup-uv@e4db8464a088ece1b920f60402e813ea4de65b8f # v4
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: Run tests
+        run: uv run python -m pytest tests/ -q --ignore=tests/test_integration.py
+      - name: Verify install
+        run: uv tool install . && seeklink status --vault /tmp || true

.gitignore

@@ -20,3 +20,6 @@ wheels/
 
 # Environment
 .env
+
+# Security reports (local only)
+.gstack/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siyuan Sun
+
+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.

README.md

@@ -1,52 +1,169 @@
 # SeekLink
 
-Hybrid semantic search and link discovery MCP server for Obsidian vaults. Fully local, no API keys needed.
+**Let your AI agent manage your Zettelkasten.**
 
-## Features
+SeekLink is an MCP server that gives AI assistants (Claude Code, Cursor, etc.) deep access to your markdown vault. It searches, discovers missing connections, and writes `[[wikilinks]]` for you — so your knowledge graph grows as you work.
 
-- **Hybrid search**: BM25 full-text + vector semantic search with RRF fusion
-- **Link discovery**: Finds related notes and writes `[[links]]` on approval
-- **Knowledge graph**: Parses `[[wikilinks]]`, tracks indegree, BFS graph traversal
-- **Bilingual**: Native Chinese + English support (jieba tokenizer + jina-embeddings-v2-base-zh)
-- **Auto-indexing**: File watcher detects changes and re-indexes automatically
+Built for people who take notes seriously and want an AI that understands their knowledge structure, not just their text.
 
-## Setup
+## What it does
+
+```
+You:   "What do I know about MCP protocol?"
+Agent: searches vault → finds 8 related notes across topics
+
+You:   "What should this note link to?"
+Agent: analyzes content → suggests 4 missing connections with relevance scores
+
+You:   "Approve the first two"
+Agent: writes [[wikilinks]] directly into your note file
+```
+
+**Six MCP tools:**
+
+| Tool | What it does |
+|------|-------------|
+| `search` | Four-channel hybrid search: keyword (BM25) + semantic (vector) + knowledge graph (indegree) + title/alias. Fused with Reciprocal Rank Fusion. Filter by tags or folder. |
+| `graph` | Explore a note's neighborhood — outgoing links, backlinks, configurable depth |
+| `suggest_links` | Find notes that should be linked but aren't. Returns scored suggestions |
+| `resolve_suggestion` | Approve (writes `[[link]]` to file) or reject a link suggestion |
+| `index` | Index a note, or list unprocessed notes |
+| `status` | Vault stats: indexed notes, graph size, watcher status |
+
+## Why SeekLink
+
+**Most MCP servers for Obsidian are file managers.** They read, write, and search text. SeekLink understands your knowledge *structure*: it parses `[[wikilinks]]`, builds a knowledge graph, tracks which notes are central (indegree), and finds connections you missed.
+
+**Chinese is a first-class citizen.** jieba tokenization for keyword search + jina-embeddings-v2-base-zh for semantic search. Not "also supports Chinese" — designed for it. Bilingual vaults (Chinese + English) work out of the box.
+
+**Fully local, headless.** Runs on your machine. No Obsidian plugins required, no API keys for search. Works from the terminal with Claude Code, or as MCP server for any client.
+
+## Install
 
 ```bash
-uv sync
+uv tool install seeklink
+# or
+pip install seeklink
 ```
 
-## Usage
+## Setup
+
+### MCP server (for Claude Code, Cursor, etc.)
 
-SeekLink runs as an MCP server — configure it in `.mcp.json`:
+Add to your MCP config:
 
 ```json
 {
   "mcpServers": {
     "seeklink": {
-      "command": "uv",
-      "args": ["run", "python", "-m", "seeklink"],
+      "command": "seeklink",
+      "args": ["serve"],
       "env": { "SEEKLINK_VAULT": "/path/to/your/vault" }
     }
   }
 }
 ```
 
-Then use the 8 tools through any MCP client (Claude Code, etc.):
+First run indexes your vault automatically. A file watcher keeps the index up to date.
 
-| Tool | Description |
-|------|-------------|
-| `search` | Hybrid BM25 + vector search with optional graph expansion |
-| `suggest_links` | Find notes worth linking to |
-| `approve_suggestion` | Accept a link suggestion (writes `[[link]]` to file) |
-| `reject_suggestion` | Dismiss a link suggestion |
-| `graph_neighbors` | Show link neighborhood (BFS) |
-| `index_note` | Index a note (chunk, embed, parse links) |
-| `get_unprocessed` | List notes needing indexing |
-| `status` | Index stats, graph size, watcher status |
+### CLI
 
-## Tests
+```bash
+seeklink search "machine learning" --vault /path/to/vault
+seeklink search "知识管理" --vault /path/to/vault --tags ai --top-k 5
+seeklink index --vault /path/to/vault
+seeklink status --vault /path/to/vault
+```
+
+## How search works
+
+SeekLink runs four search channels in parallel and merges results with Reciprocal Rank Fusion:
+
+```
+Query: "agent memory systems"
+        │
+        ├── BM25 (FTS5 + jieba) ──── keyword match ──────── weight 1.0
+        ├── Vector (jina-v2-zh) ──── semantic similarity ── weight 1.0
+        ├── Indegree ─────────────── well-linked = quality ─ weight 0.3
+        └── Title/Alias (FTS5) ──── exact name match ────── weight 3.0
+        │
+        └── RRF Fusion → ranked results
+```
+
+- **Tags filter:** `search("query", tags=["ai", "mcp"])` — only return notes with these tags
+- **Folder filter:** `search("query", folder="notes/")` — only search within a folder
+- **Expand mode:** `search("query", expand=True)` — include graph neighbors of results
+
+## Frontmatter
+
+SeekLink reads `tags` and `aliases` from YAML frontmatter:
+
+```yaml
+---
+tags: [ai, machine-learning]
+aliases: [ML, Machine Learning]
+---
+```
+
+Both inline (`[a, b]`) and block list formats supported. Aliases are searchable and used for link resolution — if a note has `aliases: [ML]`, then `[[ML]]` resolves to it.
+
+## Architecture
+
+```
+                    ┌────────────────────────────────┐
+                    │         MCP Client             │
+                    │  (Claude Code, Cursor, ...)    │
+                    └──────────┬─────────────────────┘
+                               │ stdio / SSE
+                    ┌──────────▼─────────────────────┐
+                    │      FastMCP Server             │
+                    │  6 tools, async handlers        │
+                    └──────────┬─────────────────────┘
+                               │
+          ┌────────────────────┼────────────────────┐
+          ▼                    ▼                     ▼
+   ┌─────────────┐    ┌──────────────┐     ┌──────────────┐
+   │   Search     │    │   Ingest     │     │   Watcher    │
+   │  4-ch RRF    │    │  chunk+embed │     │  watchfiles  │
+   └──────┬──────┘    │  +frontmatter│     │  auto-index  │
+          │           └──────┬───────┘     └──────────────┘
+          ▼                  ▼
+   ┌──────────────────────────────────┐
+   │          SQLite + Extensions     │
+   │  FTS5 (jieba) │ vec0 (768d)     │
+   │  sources, chunks, wiki_links    │
+   │  source_tags, fts_sources       │
+   └──────────────────────────────────┘
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SEEKLINK_VAULT` | `.` | Path to vault root |
+| `SEEKLINK_SSE_HOST` | `127.0.0.1` | SSE server bind address |
+| `SEEKLINK_SSE_PORT` | `8767` | SSE server port |
+
+## Development
 
 ```bash
-uv run python -m pytest tests/ -v
+git clone https://github.com/simonsysun/seeklink
+cd seeklink
+uv sync --dev
+uv run python -m pytest tests/ -q --ignore=tests/test_integration.py
 ```
+
+217 tests. Python 3.11+.
+
+## Roadmap
+
+- [ ] Graph intelligence: orphan detection, cluster analysis, bridge notes, knowledge gap discovery
+- [ ] Cross-encoder reranking for top-k results
+- [ ] Lightweight embedding model option (~117MB vs 330MB default)
+- [ ] PyPI automated publishing
+
+See [TODOS.md](TODOS.md) for details.
+
+## License
+
+MIT

TODOS.md

@@ -0,0 +1,25 @@
+# TODOs
+
+Deferred work for future releases. Contributions welcome.
+
+## v0.2 candidates
+
+### Cross-encoder reranking
+Re-rank top results with a cross-encoder for better precision. Needs latency benchmarking to ensure the quality gain justifies the added latency (~100-300ms per query).
+
+**Context:** The current RRF fusion (BM25 + vector + indegree + title) is already strong. Cross-encoder would be an optional second pass on the top-k results. Competitor "Hybrid Search" uses multilingual-e5 reranking.
+
+### Lightweight embedding model option
+Add `SEEKLINK_MODEL` environment variable to choose between:
+- `jinaai/jina-embeddings-v2-base-zh` (default, 330MB, best CJK)
+- A smaller multilingual model (~117MB, 100+ languages)
+
+**Context:** Deferred because adding model choice increases decision burden for new users. 330MB is acceptable in 2026. Add when community requests it.
+
+## Infrastructure
+
+### PyPI automated publishing
+GitHub Actions workflow to publish to PyPI on tag push. Currently v0.1.0 is published manually.
+
+### Integration test fixture cleanup
+Session-scoped async MCP client fixture hangs during teardown when all integration tests run together. Individual test classes pass fine. Likely a `create_connected_server_and_client_session` cleanup issue with the watcher task.

pyproject.toml

@@ -1,9 +1,23 @@
 [project]
 name = "seeklink"
 version = "0.1.0"
-description = "Hybrid semantic search MCP server for Obsidian vaults. BM25 + vector + knowledge graph, native CJK support, fully local."
+description = "Hybrid semantic search MCP server for markdown vaults. Four-channel RRF fusion (BM25 + vector + knowledge graph + title), native CJK support, fully local."
 readme = "README.md"
-requires-python = ">=3.14"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Siyuan Sun" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Text Processing :: Indexing",
+]
 dependencies = [
     "fastembed>=0.7.4",
     "jieba>=0.42.1",
@@ -13,6 +27,13 @@ dependencies = [
     "watchfiles>=1.1.1",
 ]
 
+[project.urls]
+Homepage = "https://github.com/simonsysun/seeklink"
+Repository = "https://github.com/simonsysun/seeklink"
+
+[project.scripts]
+seeklink = "seeklink.__main__:main"
+
 [dependency-groups]
 dev = [
     "anyio>=4.12.1",