memex-claude

memex-claude

Semantic skill, memory, and rule router for Claude Code. Injects relevant knowledge into your session based on what you're actually working on, instead of loading everything at once.

Built on @jim80net/memex-core — the shared engine for embedding, indexing, and searching knowledge artifacts.

Why this exists

AI coding assistants are essentially paint-by-number systems. You start with a canvas (the model) and a system prompt (the outline of the picture). Then you add your own directives — CLAUDE.md, MEMORY.md, rules — which are like adding more lines to the coloring book before you begin.

This works well at first. But as you accumulate knowledge — git workflows, ticket tracking conventions, deployment procedures, coding standards, domain-specific patterns — the coloring page gets crowded. Every session starts with all of this context loaded, whether it's relevant or not. The LLM's attention is split across git rules when you're debugging CSS, and deployment procedures when you're writing tests. Performance degrades as the corpus grows.

The solution is gradual disclosure: start with universal principles only, then bring in additional directives at the point of consumption, when the conversation actually turns toward those specific tasks. When you need to trade a ticker, the relevant know-how appears. When you're deploying, the deployment checklist surfaces. When you're just writing code, nothing extra clutters the context.

This is what memex-claude does. As skills, memories, and rules are created, they are embedded for semantic retrieval. Each type has a disclosure pattern suited to its nature:

• Skills — large procedural checklists — are gradually disclosed: a description teaser first, then the full SKILL.md when Claude chooses to use it, which may in turn reference other documents and scripts.
• Memories — generally small preferences and facts — are disclosed in full at the moment they become relevant.
• Rules — important guidelines — are disclosed in full when first relevant, then reduced to one-line reminders on subsequent matches, keeping them present without dominating the context.

The result is a system that drives the conversation according to the task at hand. Performance stays consistent even as learnings amass, because the context window carries only what's needed right now.

To manage the growing corpus, two bundled skills handle the lifecycle: /sleep organizes and migrates memories into semantically-searchable skills, while /deep-sleep trawls past conversations to extract recurring patterns and preferences. Together, the system learns from how you work, builds a corpus of guidelines, and interjects them at the right moments — becoming more intuitive over time.

How it works

User prompt → embed (local ONNX) → cosine similarity against skill index → inject top matches

┌─────────────────────────────────────────────────────┐
│               @jim80net/memex-core                   │
│  SkillIndex ←→ Cache (~/.claude/cache/memex-cache…)  │
│  embeddings (local ONNX via all-MiniLM-L6-v2)       │
│  cosineSimilarity, mtime-based rebuild               │
└──────────┬──────────────┬───────────────┬───────────┘
           │              │               │
    ┌──────▼──────┐ ┌────▼─────┐  ┌──────▼──────┐
    │ UserPrompt  │ │   Stop   │  │ PreToolUse  │
    │  Submit     │ │          │  │             │
    │ Match query │ │ Behavioral│ │ Match tool- │
    │ → inject    │ │ rules    │  │ specific    │
    │ skills +    │ │          │  │ guidance    │
    │ memories +  │ │          │  │             │
    │ rules       │ │          │  │             │
    └─────────────┘ └──────────┘  └─────────────┘

Entry types and disclosure

Type	First match	Subsequent	Matched on
rule	Full content	One-liner reminder	UserPromptSubmit
memory	Full content	Full content	UserPromptSubmit
skill	Description teaser	Full (via Read)	UserPromptSubmit
workflow	Description teaser	Full (via Read)	UserPromptSubmit
tool-guidance	Full content	Full content	PreToolUse
session-learning	Full content	Full content	UserPromptSubmit
stop-rule	Behavioral rules for Stop hook	—	Stop

GEPA enhancements

• boost — An optional frontmatter field (boost: 0.05) that nudges an entry's similarity score, useful for skills near the match threshold.
• Per-query telemetry — queryHits tracks which specific queries triggered matches, enabling data-driven query refinement during /sleep.
• Query attribution — Search results include bestQueryIndex, identifying which query in the entry's queries list was the strongest match.

Three sources

The router indexes knowledge from three locations, each at global and project scope: