feat: layered memory loading

[GoDiao]

Summary

Propose a layered memory system for MiniCode, inspired by Claude Code's CLAUDE.md hierarchy.

Claude Code's design

Claude Code loads CLAUDE.md files from multiple layers at startup:

• ~/.claude/CLAUDE.md — user global preferences
• ./CLAUDE.md or ./.claude/CLAUDE.md — project-level rules
• Nested directories — walks upward from cwd collecting CLAUDE.md files
• ./CLAUDE.local.md — personal project config, not committed to Git
• ~/.claude/projects/<path>/memory/ — auto-generated project memory
• @path include — CLAUDE.md can reference other files like @docs/architecture.md
• .claude/rules/*.md — modular rule files

All memory is injected into the model's context. More specific rules naturally take priority over broader ones.

What I plan to implement

Phase 1 — the basics:

• Read ~/.mini-code/CLAUDE.md (user global)
• Read ./CLAUDE.md or ./.mini-code/CLAUDE.md (project root), also scan ./.claude/ for compatibility
• Walk upward from cwd collecting CLAUDE.md files
• Concatenate everything into the system prompt
• Cap total content at ~50k chars

Phase 2 — follow-up PRs:

• @path include resolution
• CLAUDE.local.md
• .mini-code/rules/*.md auto-discovery
• Auto memory read/write
• /memory command to inspect loaded files

Why

Session persistence (just merged) gives MiniCode cross-session continuity. Layered memory gives it cross-session context — project knowledge and preferences persist without re-explaining every time.

Does this scope look reasonable?

[GateJustice]

Scope looks reasonable.

Just to confirm: are we planning to build MiniCode’s memory system around Claude Code’s three-layer model — global user memory, project memory, and directory-scoped memory discovered from the current working directory upward?

If yes, I think it would be useful to make that hierarchy and its precedence rules explicit in Phase 1.

[GoDiao]

Yes, confirming the three-layer structure.

After looking at cc's implementation, here's the refined Phase 1 scope:

Collection:

• Walk upward from cwd to root
• At each directory, try: MINI.md, MINI.local.md, .mini-code/MINI.md, plus compatibility scanning for CLAUDE.md, CLAUDE.local.md, .claude/CLAUDE.md
• User global: ~/.mini-code/MINI.md (also compatible with ~/.mini-code/CLAUDE.md)

Processing:

• Content hash deduplication (same approach as claw-code)
• Per-file limit ~8k chars, total limit ~20k chars, truncate with [truncated]
• Render with scope path annotation in system prompt

Render example:

# Instructions

## MINI.md (scope: /path/to/project)

[content]

## MINI.local.md (scope: /path/to/project)

[content]

Phase 2 follow-ups: @path include, .mini-code/rules/*.md, auto memory, /memory command.

Using MINI.md as MiniCode's own identity while keeping CLAUDE.md compatibility scanning. No need to rename existing files.

Unless there are objections, I'll start implementing this.

[GateJustice]

This is a strong refinement of the original scope and I agree with most of the design.

A couple of things worth making explicit (non-blocking, but important for future iterations):

• Precedence rules between layers (cwd vs parent vs global)
• Whether MINI.local.md should override MINI.md within the same directory
• Deterministic ordering guarantees after deduplication

Locking these down early would make Phase 2 features (includes, rules, auto memory) much easier to reason about.

Otherwise, looks good to proceed.

[GoDiao]

Good points, making these explicit:

1. Precedence: cwd wins over parent, parent wins over global. Loading order is global → root → ... → cwd, so cwd content appears last in the prompt and naturally takes priority.

2. MINI.local.md vs MINI.md: Within the same directory, MINI.local.md is loaded after MINI.md, so it takes precedence. Same as claw-code and Claude Code behavior.

3. Deterministic ordering after dedup: Files are kept in discovery order (root → cwd). When dedup removes a duplicate, the later occurrence (closer to cwd) wins. This ensures the most specific context survives.

Starting implementation now.

[GateJustice]

Looks great — thanks for making these rules explicit.

The precedence model and deterministic ordering are especially clear now, and this should make the behavior much easier to reason about going forward.

No further comments from my side. Looking forward to the implementation.