sp-context

sp-context

Your AI agent starts every session knowing nothing about your team. This fixes that.

sp-context is a CLI that gives any AI coding agent (Claude Code, Codex, Cursor, etc.) persistent access to your team's knowledge — decisions, architecture, playbooks, lessons learned — through a simple Git repo.

No vector database. No embeddings. No RAG pipeline. Just Git + BM25 + about 100 tokens per session for the catalog overview.

Ask your agent anything → it searches your knowledge base → returns the answer with sources.

Why not RAG / vector DB / MCP?

Approach	sp-context
Vector DB + embeddings	Git repo + BM25 search
MCP server (schema overhead)	CLI (zero schema, any agent)
Hosted service (vendor lock-in)	Local-first, your own Git repo
Complex infra to maintain	bun install and done
Costs money at scale	Free forever

Progressive loading: On session start, a hook injects a short directory overview (on the order of ~100 tokens). Your agent knows what knowledge exists without loading it all. It pulls full docs on demand via sp get.

Quick Start

# 1. Install
git clone https://github.com/qiuyanxin/sp-context.git ~/sp-context-plugin
cd ~/sp-context-plugin && bun install

# 2. Initialize your knowledge repo
sp init ~/my-team-context
# Creates a Git repo with starter templates: company mission, tech stack, glossary

# 3. Put `sp` on your PATH (pick one)
cd ~/sp-context-plugin && bun link          # recommended: global `sp` command
# or: echo 'alias sp="bun run ~/sp-context-plugin/src/cli.ts"' >> ~/.zshrc && source ~/.zshrc

# 4. Verify
sp --version
sp search "architecture"

Wire it to Claude Code (optional)

Add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "$HOME/sp-context-plugin/hooks/session-start.sh",
        "timeout": 5000
      }]
    }]
  }
}

Now every Claude Code session starts with your team's context automatically loaded.

Commands

# ── Read ──
sp search <query>                        # BM25 + CJK search
sp search <query> --type <t> --tags a,b  # Filter by type / tags
sp search <query> --limit 20 --mode or   # Max hits; OR = any term matches
sp search <query> --snippet              # Keyword context snippets
sp get <path>                            # Read full document
sp list <category> [--project <name>]      # Browse: context, decisions, …, clients, people

# ── Write ──
sp push --title <t> --type <type> --content <text>   # Add knowledge (auto-dedup)
sp push --title <t> --type <type> --file <path>      # Body from file (or stdin)
sp push --title <t> --type status --ttl 30d          # TTL → expiry in frontmatter
sp push --title <t> --type personal --category notes # people/ sub-folder (research, drafts, notes)

# ── Claude-mem ──
sp import --query "auth" --limit 20                  # Search observations → import
sp import --ids 101,102                                # Import by observation IDs

# ── Governance ──
sp doctor                                # Quality check (duplicates, stale, broken links)
sp schema                                # Introspect types, tags, stats
sp gc [--yes|-y]                         # Archive expired docs

# ── File ops ──
sp add <file|dir> [--to <path>] [--yes]  # Add local files to knowledge repo
sp delete <path>                         # Delete document (alias: sp rm)
sp move <path> --to <dir>                # Move document (alias: sp mv)

# ── Sync ──
sp sync                                  # Pull + rebuild index
sp config list|add|switch                # Manage multiple repos

How It Works

Progressive Loading (saves tokens)

Session start  → Tier 0: hook injects directory overview (~100 tokens)
On-demand      → Tier 1: sp search returns summaries (~95 tokens/hit)
Deep read      → Tier 2: sp get loads full document

Search Engine

• BM25 ranking with field weights: title(5x) > tags(3x) > keywords(2.5x) > summary(1.5x)
• CJK bigram — Chinese/Japanese/Korean search without a dictionary
• Prefix + fuzzy matching — typos are forgiven
• Full-text fallback — if index misses, scans raw markdown
• Content dedup — MD5 check on push, no duplicates

Document Types

Type	Directory	What goes here
reference	context/	Company info, product specs, competitors
decision	decisions/	Architecture, product, business decisions
learning	experience/	Lessons learned, best practices
meeting	meetings/	Meeting notes
status	plans/	Plans, progress, weekly updates
playbook	playbook/	SOPs, workflows
personal	people/	Personal workspace (optional --category for sub-folders)