janbjorge/rekal/rekal-init

Bootstrap rekal memory from a codebase. Goal: a fresh agent in a new session has enough context to work effectively without the user repeating themselves.

Requirements

1. Execute ALL steps including Tier 4 (source code scanning). Do NOT stop after reading docs and config.
2. Run every Grep command in Tier 4. Each grep with results → at least 1 memory.
3. Store at least 1 memory per source module discovered in the codebase.
4. Read high-signal docs first (CLAUDE.md, AGENTS.md). They reveal what else to scan.
5. Follow breadcrumbs. If docs reference other files or dirs, read those too.
6. Run the self-check in Step 7 before finishing.
7. On a fresh DB, skip dedup searches. Nothing to dedup against. Store directly.

Common failure: agent reads docs + config, stores ~20 memories, skips source code scanning entirely. Do not do this.

Step 0: Pre-flight

rekal health

Report current state. If the project already has memories, warn and wait for confirmation. For a fresh database, continue automatically.

Step 1: Identify the project

Determine the project name from the working directory, git remote, or config files. Prefer short, lowercase names: rekal, backend, myapp. Pass it as project="<name>" on every memory_store call below.

Step 2: Scan for knowledge sources

Search for these files in priority order. Read every file that exists. Skip what's missing.

Tier 1: High-signal project docs (read fully, read FIRST)

CLAUDE.md, AGENTS.md, .claude/CLAUDE.md
README.md, README.rst, README.txt
CONTRIBUTING.md, ARCHITECTURE.md, DESIGN.md, ADR/*.md
docs/architecture.md, docs/design.md, docs/conventions.md

Read these BEFORE other tiers. They frequently reference:

• Specific directories or modules to pay attention to
• Conventions not captured in linter configs
• Domain-specific terminology and concepts
• Workflows, procedures, and tool preferences
• Other documentation files worth reading

Follow the breadcrumbs. If CLAUDE.md says "read AGENTS.md before doing anything" or references docs/api-guide.md, read those files too. If AGENTS.md describes a specific architecture, that's a memory.

Tier 2: Config and dependency manifests (read fully)

pyproject.toml, setup.cfg, setup.py, requirements*.txt
package.json, tsconfig.json, deno.json
Cargo.toml, go.mod, Gemfile, build.gradle, pom.xml
Makefile, Justfile, Taskfile.yml
docker-compose.yml, Dockerfile
.github/workflows/*.yml, .gitlab-ci.yml, Jenkinsfile
.env.example, .envrc

Extract: stack + versions, key deps with purpose, CI pipeline steps, Docker setup, env vars needed.

Tier 3: Structural exploration

# Directory tree: top 3 levels via Glob
Glob pattern: "**/*/", max-depth 3
 
# Entry points: look for main/index/app files in src/ and project root
Glob: "main.*", "app.*", "index.*", "src/main.*", "src/index.*", "cmd/*/main.*"
 
# Config files that reveal conventions
.editorconfig, .prettierrc, .eslintrc*, ruff.toml, .ruff.toml
mypy.ini, pyrightconfig.json, tox.ini

Also explore anything Tier 1 docs pointed to: scripts/ dirs, specific modules mentioned by name, etc.

Tier 4: Source code structure (MANDATORY)

You MUST execute every sub-step below.

Scan the codebase through an architectural lens. The goal is to map the system's layers, not just list files but understand what role each piece of code plays.

4a. Discover all modules/packages:

Use the directory tree from Tier 3 and the stack from Tier 2 to identify top-level source units (packages, modules, crates, services, whatever the project calls them). Glob for src/*/ or equivalent. List every module found. Store at least 1 memory per module.

4b. Map the architecture by layer:

For EACH module from 4a, read its entry/index file and 1-2 key files. Classify what you find and store memories accordingly:

Domain (entities, value objects, business rules):

• Find type/model definitions: look in dirs named models, entities, domain, types, schemas
• Find enums and constants: these define domain vocabulary (statuses, categories, roles)
• Find error/exception types: these define domain boundaries and business rule violations

Store: what entities exist, their relationships, invariants, domain-specific terms.

Ports (interfaces the domain exposes or depends on):

• Find abstract interfaces, contracts, traits: look for dirs named ports, interfaces, contracts
• Find types named Repository, Service, Gateway, Port, Store: these are usually boundaries

Store: what abstractions exist, which are inbound (driving) vs outbound (driven).

Adapters (how ports connect to the outside world):

Inbound (drive the application):

• Find route/handler definitions: HTTP endpoints, GraphQL resolvers, gRPC services, CLI commands
• Find message consumers/subscribers
• Look in dirs named routes, controllers, handlers, adapters, api

Outbound (driven by the application):

• Find persistence implementations: SQL files, ORM models, repository classes
• Read latest 3-5 migration files and schema definitions
• Find event/message publishers
• Find external service client wrappers (HTTP clients, cloud SDK usage)

Store: API surface, persistence strategy, external integrations, event patterns.

Infrastructure (wiring, config, middleware, startup):

• Find DI/wiring configuration
• Find middleware/interceptor chains
• Look in dirs named config, infrastructure, wire, di

Store: how layers are wired together, middleware chain.

4c. Read schema files in detail:

Find and read files in model/schema/entity directories. Read migration files, proto files, GraphQL schemas, OpenAPI specs if they exist.

Store: entity relationships, key fields, constraints worth knowing.

Each discovery → at least 1 memory summarizing findings. Nothing found → skip.

Tier 5: Test structure and patterns

# Find test directories and config
Glob: "tests/", "test/", "spec/", "testdata/", "fixtures/"
 
# Read test setup: fixtures, helpers, factories, shared config
Look for setup/helper/conftest/factory files in test dirs
 
# Skim test names for domain concepts: just names, not implementations

Store: test framework, fixtures/factories, DB/service strategy, parallelization.

Do NOT read

• Lock files (package-lock.json, uv.lock, Cargo.lock, yarn.lock)
• Generated files, build artifacts, node_modules, dist/, .git/
• Binary files, images, fonts
• Individual test implementations (test names suffice)
• Vendored/third-party code

Step 3: Extract knowledge candidates

For each file read, extract knowledge that passes this filter:

Would a fresh agent work faster or make fewer mistakes knowing this?
├── YES → candidate
└── NO  → skip

Bias toward storing. The cost of a redundant memory (superseded later) is low. The cost of a missing memory (user repeats themselves, agent makes wrong assumption) is high.

What to extract

Architecture & structure:

Domain layer:

Ports & adapters:

Infrastructure & operations:

What NOT to extract

• Verbatim content from CLAUDE.md or AGENTS.md. Those are loaded every session. DO synthesize cross-cutting knowledge that spans multiple files into single memories.
• Individual function signatures or line numbers: trivially re-discoverable
• Boilerplate from templates (default CI configs, standard Dockerfile patterns)
• Version numbers that change frequently (pin knowledge to concepts, not versions)
• License text, badges, marketing copy

Step 4: Deduplicate and store

On a fresh DB (no existing memories), skip the recall step entirely. There's nothing to dedup against. Store directly. This dramatically speeds up init.

On re-init (memories already exist), recall before each store:

memory_build_context(query="<candidate topic>")

Recall results?
├── No match         → memory_store(content, tags, project)
├── Same info exists → SKIP (duplicate)
├── Outdated version → memory_store(content, replaces="<old_id>")
└── Contradicts      → memory_store(content, replaces="<old_id>"), include what changed

Content rules

Every memory must be self-contained. A fresh agent with zero context reads it.

Good: "rekal uses three-layer architecture: MCP adapter (mcp_adapter.py) creates
      FastMCP server and manages lifespan → tool modules in adapters/tools/ are
      thin @mcp.tool() wrappers → SqliteDatabase dataclass holds all SQL queries.
      New tool = add method to SqliteDatabase + thin wrapper in tools/*.py."
 
Bad:  "Three-layer architecture"          (too vague)
Bad:  "See AGENTS.md for architecture"    (not self-contained)
Bad:  "As described in the README..."     (references source)

Tags must be specific

Good: ["architecture", "mcp", "sqlite", "tool-pattern"]
Bad:  ["code", "project", "structure"]

Step 5: Batch efficiently

Group related candidates. Store in logical order: