openclew 0.0.1 → 0.2.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,299 @@
+# openclew
+
+> Long Life Memory for LLMs
+
+**Your agent forgets. Your project remembers.**
+
+In Greek mythology, Ariadne gave Theseus a *clew* — a ball of thread — to find his way out of the Minotaur's labyrinth. That thread is the etymological origin of the word "clue." It wasn't a map. It wasn't a search engine. It was a continuous trail that connected where you've been to where you are.
+
+That's what openclew does for your project. Every decision, every architectural choice, every hard-won lesson — laid down as a thread that any reader (human or AI) can follow. Not scattered across wikis, chat logs, and CLAUDE.md files that grow until they're unreadable. One trail. One source of truth.
+
+---
+
+## Why this exists
+
+AI agents are powerful, but they're amnesiac. Every new session starts from zero. The usual fixes don't work:
+
+| Approach | What goes wrong |
+|----------|----------------|
+| CLAUDE.md / .cursorrules | Grows into an unreadable wall of text. Agent loads everything, wastes tokens on irrelevant context |
+| Agent memory (Claude, Copilot) | Opaque, not versioned, not shareable with the team |
+| Wiki / Notion | Disconnected from the code, goes stale |
+| README.md | Not structured for AI consumption |
+| Nothing | Re-explain everything every session |
+
+The deeper problem isn't *storage* — it's **navigation**. A project with 50 documents and 200K tokens of knowledge can't be loaded in full. The real question an agent (or a human) needs to answer is:
+
+> **"Should I read this document?"**
+
+Not "does this file contain the word `auth`?" — that's pattern matching. The question is about *relevance*. And you can only answer it if documents are designed to be skimmed before they're read.
+
+---
+
+## The idea: 3 levels of depth
+
+Every openclew document has 3 levels. Same file, different depths — for different needs.
+
+```
+┌─────────────────────────────────────────────┐
+│  L1 — Metadata                              │
+│  type, subject, status, keywords            │
+│  → "Should I read this?" — decidable in     │
+│     2 seconds, ~40 tokens per doc            │
+│  → Auto-indexed, machine-parseable          │
+├─────────────────────────────────────────────┤
+│  L2 — Summary                               │
+│  Objective, key points, solution            │
+│  → The full picture in 30 seconds           │
+│  → Enough for most decisions                │
+├─────────────────────────────────────────────┤
+│  L3 — Details                               │
+│  Code, examples, history, edge cases        │
+│  → Deep-dive only when actually needed      │
+│  → Most readers never go here               │
+└─────────────────────────────────────────────┘
+```
+
+This isn't just an organizational trick — it's a **token efficiency strategy**. A project with 50 docs:
+
+| Strategy | Tokens consumed | Relevance |
+|----------|----------------|-----------|
+| Load everything | ~200K | Mostly noise |
+| Grep for keywords | Variable | Misses context, false positives |
+| **Read all L1s, then L2 of relevant docs** | **~2K + 2-3 docs** | **Precise, contextual** |
+
+L1 answers "should I read this?" L2 answers "what do I need to know?" L3 is there when you need the details. Most of the time, you don't.
+
+---
+
+## Two types of docs
+
+| Type | Location | Role | Mutability |
+|------|----------|------|------------|
+| **Living** | `doc/_SUBJECT.md` | Living knowledge (architecture, conventions, decisions) | Updated over time |
+| **Log** | `doc/log/YYYY-MM-DD_subject.md` | Frozen facts (what happened, what was decided) | Never modified |
+
+**Living docs** are your project's brain — they evolve as the project evolves.
+**Logs** are your project's journal — immutable records of what happened and why.
+
+Together, they form the thread. The living docs tell you where you are. The logs tell you how you got here.
+
+---
+
+## Quick start (5 minutes)
+
+### 1. Create the structure
+
+```bash
+mkdir -p doc/log
+```
+
+### 2. Copy the templates
+
+Download from [`templates/`](templates/) or create manually:
+
+<details>
+<summary><b>templates/living.md</b> — for living knowledge</summary>
+
+```markdown
+<!-- L1_START -->
+# L1 - Metadata
+type: Reference | Architecture | Guide | Analysis
+subject: Short title (< 60 chars)
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+short_story: 1-2 sentences. What this doc covers and what it concludes.
+status: Active | Stable | Archived
+category: Main domain (e.g. Auth, API, Database, UI...)
+keywords: [tag1, tag2, tag3]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this document exists -->
+
+## Key points
+<!-- 3-5 essential takeaways -->
+
+## Solution
+<!-- Recommended approach or pattern -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Full technical content: examples, code, references... -->
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| YYYY-MM-DD | Initial creation |
+<!-- L3_END -->
+```
+
+</details>
+
+<details>
+<summary><b>templates/log.md</b> — for frozen facts</summary>
+
+```markdown
+<!-- L1_START -->
+# L1 - Metadata
+date: YYYY-MM-DD
+type: Bug | Feature | Refactor | Doc | Deploy
+subject: Short title (< 60 chars)
+short_story: 1-2 sentences. What happened and what was the outcome.
+status: Done | In progress | Abandoned
+category: Main domain
+keywords: [tag1, tag2, tag3]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Problem
+<!-- What was observed -->
+
+## Solution
+<!-- How it was resolved -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Technical details: code changes, debugging steps, references... -->
+<!-- L3_END -->
+```
+
+</details>
+
+### 3. Write your first doc
+
+```bash
+cp templates/living.md doc/_ARCHITECTURE.md
+```
+
+Edit it — describe your project's architecture. Fill in L1 (metadata), L2 (summary), skip L3 if you don't need it yet.
+
+### 4. Point your agent to it
+
+Add this to your `CLAUDE.md`, `.cursorrules`, or `AGENTS.md`:
+
+```markdown
+## Project knowledge
+
+Documentation lives in `doc/`. Each doc has 3 levels (L1/L2/L3).
+- Read L1 first to decide if you need more
+- Living docs: `doc/_*.md` (living knowledge, updated)
+- Logs: `doc/log/YYYY-MM-DD_*.md` (frozen facts, never modified)
+- Index: `doc/_INDEX.md` (auto-generated, start here)
+```
+
+### 5. Auto-generate the index (optional)
+
+Copy [`hooks/generate-index.py`](hooks/generate-index.py) to your project and add it as a pre-commit hook:
+
+```bash
+# Option A: git hook
+cp hooks/generate-index.py .git/hooks/generate-index.py
+echo 'python .git/hooks/generate-index.py && git add doc/_INDEX.md' >> .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+
+# Option B: pre-commit framework
+# See hooks/README.md for .pre-commit-config.yaml setup
+```
+
+The index auto-regenerates on every commit. Never edit it manually.
+
+---
+
+## How it works in practice
+
+**Session 1** — You're setting up auth:
+```
+doc/
+├── _ARCHITECTURE.md          # Your stack, main patterns
+└── log/
+    └── 2026-03-07_setup-auth.md   # What you did, decisions made
+```
+
+**Session 5** — New agent session, different feature:
+```
+Agent reads doc/_INDEX.md (auto-generated)
+  → Scans all L1s: "Should I read this?"
+  → _ARCHITECTURE.md → yes → reads L2
+  → setup-auth log → relevant → reads L2
+  → Skips the rest
+  → Full context in ~1K tokens instead of 50K
+```
+
+**Session 20** — Your project has grown:
+```
+doc/
+├── _INDEX.md                      # Auto-generated, 30 entries
+├── _ARCHITECTURE.md               # Updated 12 times
+├── _AUTH.md                       # Extracted when auth got complex
+├── _API_CONVENTIONS.md            # Team conventions
+├── _KNOWN_ISSUES.md               # Active gotchas
+└── log/
+    ├── 2026-03-07_setup-auth.md
+    ├── 2026-03-10_migrate-db.md
+    ├── 2026-03-15_fix-token-refresh.md
+    └── ... (20 more)
+```
+
+30 docs. The agent scans all L1s in 2 seconds, reads the 3 that matter, and starts working with full context. A new teammate does the same — reads L2s to get up to speed in minutes. Same docs, same truth, different depth.
+
+---
+
+## Principles
+
+- **"Should I read this?"** — L1 exists to answer this question. If it can't, the L1 is poorly written.
+- **Shared knowledge** — Same docs for humans and AI. One source, multiple readers.
+- **SSOT** (Single Source of Truth) — Each piece of information lives in one place.
+- **Logs are immutable** — Once written, never modified. Frozen facts.
+- **Living docs evolve** — They evolve as the project evolves.
+- **Index is auto-generated** — Never edit `_INDEX.md` manually.
+
+---
+
+## Works with everything
+
+**AI agents:** Claude Code, Cursor, Copilot, Windsurf, Codex, Zed, Kiro, Aider, Cline, Gemini CLI...
+
+**Workflow frameworks:** BMAD, Spec Kit, or any methodology — openclew handles knowledge, your framework handles process.
+
+**It's just Markdown.** No runtime, no dependencies, no lock-in. Git-versioned, diffable, reviewable in PRs. If you stop using it, the docs are still useful — to humans and agents alike.
+
+---
+
+## Compared to alternatives
+
+| Feature | CLAUDE.md | Cline Memory Bank | BMAD | openclew |
+|---------|-----------|-------------------|------|----------|
+| Readable by humans AND agents | partial | partial | yes | **yes** |
+| Levels of depth (L1/L2/L3) | - | - | - | **yes** |
+| "Should I read this?" (L1 triage) | - | - | - | **yes** |
+| Token-efficient navigation | - | - | partial | **yes** |
+| Auto-generated index | - | - | CSV | **yes** |
+| Immutable logs | - | - | - | **yes** |
+| Git-versioned | yes | yes | yes | **yes** |
+| Cross-project | - | - | - | **yes** |
+| Tool-agnostic | Claude only | Cline only | multi | **yes** |
+
+---
+
+## License
+
+MIT — use it however you want.

package/bin/openclew.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+const { resolve } = require("path");
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const USAGE = `
+openclew — Long Life Memory for LLMs
+
+Usage:
+  openclew init                    Set up openclew in the current project
+  openclew new <title>             Create a living doc (evolves with the project)
+  openclew log <title>             Create a session log (frozen facts)
+  openclew checkout                End-of-session summary + log creation
+  openclew index                   Regenerate doc/_INDEX.md
+  openclew help                    Show this help
+
+Options:
+  --no-hook                        Skip pre-commit hook installation (init)
+  --no-inject                      Skip instruction file injection (init)
+
+Getting started:
+  npx openclew init                1. Set up doc/ + guide + examples + git hook
+  # Edit doc/_ARCHITECTURE.md      2. Replace the example with your project's architecture
+  openclew new "API design"        3. Create your own living docs
+  git commit                       4. Index auto-regenerates on commit
+
+Docs have 3 levels: L1 (metadata) → L2 (summary) → L3 (details).
+Agents read L1 to decide what's relevant, then L2 for context.
+More at: https://github.com/openclew/openclew
+`.trim();
+
+if (!command || command === "help" || command === "--help" || command === "-h") {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+const commands = {
+  init: () => require("../lib/init"),
+  new: () => require("../lib/new-doc"),
+  log: () => require("../lib/new-log"),
+  checkout: () => require("../lib/checkout"),
+  index: () => require("../lib/index-gen"),
+};
+
+if (!commands[command]) {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Run 'openclew help' for usage.`);
+  process.exit(1);
+}
+
+commands[command]();

package/hooks/generate-index.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+openclew index generator.
+
+Scans doc/_*.md (living docs) and doc/log/*.md (logs),
+parses L1 metadata blocks, and generates doc/_INDEX.md.
+
+Usage:
+    python generate-index.py              # from project root
+    python generate-index.py /path/to/doc # custom doc directory
+
+Idempotent: running twice produces the same output.
+Zero dependencies: Python 3.8+ standard library only.
+"""
+
+import os
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+def find_doc_dir():
+    """Find the doc/ directory."""
+    if len(sys.argv) > 1:
+        doc_dir = Path(sys.argv[1])
+    else:
+        doc_dir = Path("doc")
+
+    if not doc_dir.is_dir():
+        print(f"No '{doc_dir}' directory found. Nothing to index.")
+        sys.exit(0)
+
+    return doc_dir
+
+
+def parse_l1(filepath):
+    """Extract L1 metadata from a file."""
+    try:
+        content = filepath.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+    match = re.search(
+        r"<!--\s*L1_START\s*-->(.+?)<!--\s*L1_END\s*-->",
+        content,
+        re.DOTALL,
+    )
+    if not match:
+        return None
+
+    block = match.group(1)
+    meta = {}
+    for line in block.splitlines():
+        line = line.strip()
+        if line.startswith("#") or not line:
+            continue
+        if ":" in line:
+            key, _, value = line.partition(":")
+            meta[key.strip().lower()] = value.strip()
+
+    return meta
+
+
+def collect_docs(doc_dir):
+    """Collect living docs and logs with their L1 metadata."""
+    living_docs = []
+    logs = []
+
+    # Living docs: doc/_*.md
+    for f in sorted(doc_dir.glob("_*.md")):
+        if f.name == "_INDEX.md":
+            continue
+        meta = parse_l1(f)
+        if meta:
+            living_docs.append((f, meta))
+
+    # Log docs: doc/log/*.md
+    log_dir = doc_dir / "log"
+    if log_dir.is_dir():
+        for f in sorted(log_dir.glob("*.md"), reverse=True):
+            meta = parse_l1(f)
+            if meta:
+                logs.append((f, meta))
+
+    return living_docs, logs
+
+
+def generate_index(doc_dir, living_docs, logs):
+    """Generate _INDEX.md content."""
+    now = datetime.now().strftime("%Y-%m-%d %H:%M")
+    lines = [
+        f"# Project Knowledge Index",
+        f"",
+        f"> Auto-generated by [openclew](https://github.com/openclew/openclew) on {now}.",
+        f"> Do not edit manually — rebuilt from L1 metadata on every commit.",
+        f"",
+    ]
+
+    # Living docs section
+    lines.append("## Living docs")
+    lines.append("")
+    if living_docs:
+        lines.append("| Document | Subject | Status | Category |")
+        lines.append("|----------|---------|--------|----------|")
+        for f, meta in living_docs:
+            name = f.name
+            subject = meta.get("subject", "—")
+            status = meta.get("status", "—")
+            category = meta.get("category", "—")
+            rel_path = f.relative_to(doc_dir.parent)
+            lines.append(f"| [{name}]({rel_path}) | {subject} | {status} | {category} |")
+    else:
+        lines.append("_No living docs yet. Create one with `templates/living.md`._")
+    lines.append("")
+
+    # Logs section (last 20)
+    lines.append("## Recent logs")
+    lines.append("")
+    display_logs = logs[:20]
+    if display_logs:
+        lines.append("| Date | Subject | Status | Category |")
+        lines.append("|------|---------|--------|----------|")
+        for f, meta in display_logs:
+            date = meta.get("date", f.stem[:10])
+            subject = meta.get("subject", "—")
+            status = meta.get("status", "—")
+            category = meta.get("category", "—")
+            rel_path = f.relative_to(doc_dir.parent)
+            lines.append(f"| {date} | [{subject}]({rel_path}) | {status} | {category} |")
+        if len(logs) > 20:
+            lines.append(f"")
+            lines.append(f"_{len(logs) - 20} older logs not shown._")
+    else:
+        lines.append("_No logs yet. Create one with `templates/log.md`._")
+    lines.append("")
+
+    # Stats
+    lines.append("---")
+    lines.append(f"**{len(living_docs)}** living docs, **{len(logs)}** logs.")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def main():
+    doc_dir = find_doc_dir()
+    living_docs, logs = collect_docs(doc_dir)
+    index_content = generate_index(doc_dir, living_docs, logs)
+
+    index_path = doc_dir / "_INDEX.md"
+    index_path.write_text(index_content, encoding="utf-8")
+    print(f"Generated {index_path} ({len(living_docs)} living docs, {len(logs)} logs)")
+
+
+if __name__ == "__main__":
+    main()