memctl 0.2.1__tar.gz → 0.4.0__tar.gz

{memctl-0.2.1 → memctl-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memctl
-Version: 0.2.1
+Version: 0.4.0
 Summary: A Unix-native memory control plane for LLM orchestration
 Author-email: Olivier Vitrac <olivier.vitrac@adservio.fr>
 License: MIT
@@ -150,7 +150,34 @@ memctl search "authentication"
 memctl search "database" --json -k 5
 ```
 
-### 5. Inspect and manage
+### 5. Inspect a folder (one-liner)
+
+```bash
+# Auto-mounts, auto-syncs, and inspects — all in one command
+memctl inspect docs/
+
+# Same in JSON (for scripts)
+memctl inspect docs/ --json
+
+# Skip sync (use cached state)
+memctl inspect docs/ --no-sync
+```
+
+`inspect` auto-mounts the folder if needed, checks staleness, syncs only if stale, and produces a structural summary. All implicit actions are announced on stderr.
+
+### 6. Chat with memory-backed context
+
+```bash
+# Interactive chat with any LLM
+memctl chat --llm "claude -p" --session
+
+# With pre-ingested files and answer storage
+memctl chat --llm "ollama run granite3.1:2b" --source docs/ --store --session
+```
+
+Each question recalls from the memory store, sends context + question to the LLM, and displays the answer. `--session` keeps a sliding window of recent Q&A pairs. `--store` persists answers as STM items.
+
+### 7. Manage
 
 ```bash
 memctl show MEM-abc123def456     # Show item details
@@ -180,6 +207,10 @@ memctl <command> [options]
 | `stats` | Store statistics |
 | `consolidate [--dry-run]` | Deterministic merge of similar STM items |
 | `loop QUERY --llm CMD` | Bounded recall-answer loop with LLM |
+| `mount PATH` | Register a folder as a structured source |
+| `sync [PATH]` | Delta-sync mounted folders into the store |
+| `inspect [PATH]` | Structural inspection with auto-mount and auto-sync |
+| `chat --llm CMD` | Interactive memory-backed chat REPL |
 | `serve` | Start MCP server (requires `memctl[mcp]`) |
 
 ### Global Flags
@@ -291,6 +322,77 @@ memctl push "database schema" --source src/ \
 memctl loop --replay trace.jsonl "original question"
 ```
 
+#### `memctl mount`
+
+```bash
+memctl mount PATH [--name NAME] [--ignore PATTERN ...] [--lang HINT]
+memctl mount --list
+memctl mount --remove ID_OR_NAME
+```
+
+Registers a folder as a structured source. Stores metadata only — no scanning, no ingestion. The folder contents are synced separately via `sync` or automatically via `inspect`.
+
+#### `memctl sync`
+
+```bash
+memctl sync [PATH] [--full] [--json] [--quiet]
+```
+
+Delta-syncs mounted folders into the memory store. Uses a 3-tier delta rule:
+1. **New file** (not in DB) → ingest
+2. **Size + mtime match** → fast skip (no hashing)
+3. **Hash compare** → ingest only if content changed
+
+If `PATH` is given but not yet mounted, it is auto-registered first. `--full` forces re-processing of all files.
+
+#### `memctl inspect`
+
+```bash
+# Orchestration mode — auto-mounts, auto-syncs, and inspects
+memctl inspect PATH [--sync auto|always|never] [--no-sync] [--mount-mode persist|ephemeral]
+                    [--budget N] [--ignore PATTERN ...] [--json] [--quiet]
+
+# Classic mode — inspect an existing mount by ID/name
+memctl inspect --mount ID_OR_NAME [--budget N] [--json] [--quiet]
+```
+
+When given a positional `PATH`, inspect operates in **orchestration mode**:
+1. **Auto-mount** — registers the folder if not already mounted
+2. **Staleness check** — compares disk inventory (path/size/mtime triples) against the store
+3. **Auto-sync** — runs delta sync only if stale (or always/never per `--sync`)
+4. **Inspect** — generates a deterministic structural summary
+
+Output includes file/chunk/size totals, per-folder breakdown, per-extension distribution, top-5 largest files, and rule-based observations. All paths in output are mount-relative (never absolute).
+
+`--mount-mode ephemeral` removes the mount record after inspection (corpus data is preserved). `--no-sync` is shorthand for `--sync never`.
+
+All implicit actions (mount, sync) are announced on stderr. `--quiet` suppresses them.
+
+#### `memctl chat`
+
+```bash
+memctl chat --llm CMD [--session] [--store] [--protocol passive|json|regex]
+            [--max-calls N] [--budget N] [--source FILE ...] [--quiet]
+```
+
+Interactive memory-backed chat REPL. Each turn: FTS5 recall from the memory store, send context + question to the LLM, display the answer.
+
+**Stateless by default.** Each question sees only the memory store — no hidden conversation state.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--llm CMD` | *(required)* | LLM command (e.g. `"claude -p"`, `"ollama run granite3.1:2b"`) |
+| `--protocol` | `passive` | LLM output protocol. `passive` = single-pass; `json` = iterative refinement |
+| `--max-calls` | `1` | Max loop iterations per turn |
+| `--session` | off | Enable in-memory session context (sliding window of recent Q&A) |
+| `--history-turns` | `5` | Session window size (turns) |
+| `--session-budget` | `4000` | Session block character limit |
+| `--store` | off | Persist each answer as STM item |
+| `--source FILE...` | *(none)* | Pre-ingest files before starting |
+| `--tags` | `chat` | Tags for stored items (comma-separated) |
+
+**stdout purity:** answers go to stdout only. Prompt, banner, and hints go to stderr.
+
 ---
 
 ## Environment Variables
@@ -348,6 +450,18 @@ memctl search "" --json | jq -c '.[]'
 
 # Iterative recall-answer loop with trace
 memctl push "auth flow" --source docs/ | memctl loop "auth flow" --llm "claude -p" --trace
+
+# One-liner: inspect a folder (auto-mount + auto-sync)
+memctl inspect docs/
+
+# Inspect in JSON, pipe to jq for extension breakdown
+memctl inspect src/ --json | jq '.extensions'
+
+# Inspect without syncing (use cached state)
+memctl inspect docs/ --no-sync --json
+
+# Interactive chat with pre-ingested docs
+memctl chat --llm "claude -p" --source docs/ --session --store
 ```
 
 ---
@@ -402,14 +516,18 @@ Tool names use the `memory_*` prefix for drop-in compatibility with RAGIX.
 ```
 memctl/
 ├── types.py           Data model (MemoryItem, MemoryProposal, MemoryEvent, MemoryLink)
-├── store.py           SQLite + FTS5 + WAL backend (9 tables + schema_meta)
+├── store.py           SQLite + FTS5 + WAL backend (10 tables + schema_meta)
 ├── extract.py         Text extraction (text files + binary format dispatch)
 ├── ingest.py          Paragraph chunking, SHA-256 dedup, source resolution
 ├── policy.py          Write governance (30 patterns: secrets, injection, instructional)
 ├── config.py          Dataclass configuration
 ├── similarity.py      Stdlib text similarity (Jaccard + SequenceMatcher)
 ├── loop.py            Bounded recall-answer loop controller
-├── cli.py             9 CLI commands
+├── mount.py           Folder mount registration and management
+├── sync.py            Delta sync with 3-tier change detection
+├── inspect.py         Structural inspection and orchestration
+├── chat.py            Interactive memory-backed chat REPL
+├── cli.py             13 CLI commands
 ├── consolidate.py     Deterministic merge (Jaccard clustering, no LLM)
 ├── proposer.py        LLM output parsing (delimiter + regex)
 └── mcp/
@@ -418,7 +536,7 @@ memctl/
     └── server.py      FastMCP server entry point
 ```
 
-16 source files. ~5,300 lines. Zero compiled dependencies for core.
+20 source files. ~7,700 lines. Zero compiled dependencies for core.
 
 ### Memory Tiers
 
@@ -485,7 +603,7 @@ Deterministic, no-LLM merge pipeline:
 
 ## Database Schema
 
-Single SQLite file with WAL mode. 9 tables + 1 FTS5 virtual table:
+Single SQLite file with WAL mode. 10 tables + 1 FTS5 virtual table:
 
 | Table | Purpose |
 |-------|---------|
@@ -494,13 +612,14 @@ Single SQLite file with WAL mode. 9 tables + 1 FTS5 virtual table:
 | `memory_events` | Audit log (every read/write/consolidate) |
 | `memory_links` | Directional relationships (supersedes, supports, etc.) |
 | `memory_embeddings` | Reserved for RAGIX (empty in memctl) |
-| `corpus_hashes` | SHA-256 file dedup registry |
+| `corpus_hashes` | SHA-256 file dedup + mount metadata (mount_id, rel_path, ext, size_bytes, mtime_epoch, lang_hint) |
 | `corpus_metadata` | Corpus-level metadata |
 | `schema_meta` | Schema version, creation info |
 | `memory_palace_locations` | Reserved for RAGIX |
+| `memory_mounts` | Registered folder mounts (path, name, ignore patterns, lang hint) |
 | `memory_items_fts` | FTS5 virtual table for full-text search |
 
-Schema version is tracked in `schema_meta`. Current: `SCHEMA_VERSION=1`.
+Schema version is tracked in `schema_meta`. Current: `SCHEMA_VERSION=2`. Migration from v1 is additive (ALTER TABLE ADD COLUMN) and idempotent.
 
 ---
 
@@ -518,10 +637,11 @@ ragix memory stats --db /path/to/your/.memory/memory.db
 
 | Feature | memctl | RAGIX |
 |---------|--------|-------|
-| SQLite schema | Identical | Identical |
+| SQLite schema | Forward-compatible (RAGIX can open memctl DBs) | Superset |
 | Injection format | `format_version=1` | `format_version=1` |
 | MCP tool names | `memory_*` | `memory_*` |
 | FTS5 recall | Yes | Yes (+ hybrid embeddings) |
+| Folder mount + sync | Yes (v0.3+) | No |
 | Embeddings | No | Yes (FAISS + Ollama) |
 | LLM-assisted merge | No | Yes |
 | Graph-RAG | No | Yes |
@@ -575,7 +695,7 @@ pip install memctl[dev]
 pytest tests/ -v
 ```
 
-332 tests covering types, store, policy, ingest, text extraction, similarity, loop controller, forward compatibility, contracts, CLI (subprocess), and pipe composition.
+492 tests across 15 test files covering types, store, policy, ingest, text extraction, similarity, loop controller, mount, sync, inspect, chat, forward compatibility, contracts, CLI (subprocess), and pipe composition.
 
 ---
 

{memctl-0.2.1 → memctl-0.4.0}/README.md

@@ -107,7 +107,34 @@ memctl search "authentication"
 memctl search "database" --json -k 5
 ```
 
-### 5. Inspect and manage
+### 5. Inspect a folder (one-liner)
+
+```bash
+# Auto-mounts, auto-syncs, and inspects — all in one command
+memctl inspect docs/
+
+# Same in JSON (for scripts)
+memctl inspect docs/ --json
+
+# Skip sync (use cached state)
+memctl inspect docs/ --no-sync
+```
+
+`inspect` auto-mounts the folder if needed, checks staleness, syncs only if stale, and produces a structural summary. All implicit actions are announced on stderr.
+
+### 6. Chat with memory-backed context
+
+```bash
+# Interactive chat with any LLM
+memctl chat --llm "claude -p" --session
+
+# With pre-ingested files and answer storage
+memctl chat --llm "ollama run granite3.1:2b" --source docs/ --store --session
+```
+
+Each question recalls from the memory store, sends context + question to the LLM, and displays the answer. `--session` keeps a sliding window of recent Q&A pairs. `--store` persists answers as STM items.
+
+### 7. Manage
 
 ```bash
 memctl show MEM-abc123def456     # Show item details
@@ -137,6 +164,10 @@ memctl <command> [options]
 | `stats` | Store statistics |
 | `consolidate [--dry-run]` | Deterministic merge of similar STM items |
 | `loop QUERY --llm CMD` | Bounded recall-answer loop with LLM |
+| `mount PATH` | Register a folder as a structured source |
+| `sync [PATH]` | Delta-sync mounted folders into the store |
+| `inspect [PATH]` | Structural inspection with auto-mount and auto-sync |
+| `chat --llm CMD` | Interactive memory-backed chat REPL |
 | `serve` | Start MCP server (requires `memctl[mcp]`) |
 
 ### Global Flags
@@ -248,6 +279,77 @@ memctl push "database schema" --source src/ \
 memctl loop --replay trace.jsonl "original question"
 ```
 
+#### `memctl mount`
+
+```bash
+memctl mount PATH [--name NAME] [--ignore PATTERN ...] [--lang HINT]
+memctl mount --list
+memctl mount --remove ID_OR_NAME
+```
+
+Registers a folder as a structured source. Stores metadata only — no scanning, no ingestion. The folder contents are synced separately via `sync` or automatically via `inspect`.
+
+#### `memctl sync`
+
+```bash
+memctl sync [PATH] [--full] [--json] [--quiet]
+```
+
+Delta-syncs mounted folders into the memory store. Uses a 3-tier delta rule:
+1. **New file** (not in DB) → ingest
+2. **Size + mtime match** → fast skip (no hashing)
+3. **Hash compare** → ingest only if content changed
+
+If `PATH` is given but not yet mounted, it is auto-registered first. `--full` forces re-processing of all files.
+
+#### `memctl inspect`
+
+```bash
+# Orchestration mode — auto-mounts, auto-syncs, and inspects
+memctl inspect PATH [--sync auto|always|never] [--no-sync] [--mount-mode persist|ephemeral]
+                    [--budget N] [--ignore PATTERN ...] [--json] [--quiet]
+
+# Classic mode — inspect an existing mount by ID/name
+memctl inspect --mount ID_OR_NAME [--budget N] [--json] [--quiet]
+```
+
+When given a positional `PATH`, inspect operates in **orchestration mode**:
+1. **Auto-mount** — registers the folder if not already mounted
+2. **Staleness check** — compares disk inventory (path/size/mtime triples) against the store
+3. **Auto-sync** — runs delta sync only if stale (or always/never per `--sync`)
+4. **Inspect** — generates a deterministic structural summary
+
+Output includes file/chunk/size totals, per-folder breakdown, per-extension distribution, top-5 largest files, and rule-based observations. All paths in output are mount-relative (never absolute).
+
+`--mount-mode ephemeral` removes the mount record after inspection (corpus data is preserved). `--no-sync` is shorthand for `--sync never`.
+
+All implicit actions (mount, sync) are announced on stderr. `--quiet` suppresses them.
+
+#### `memctl chat`
+
+```bash
+memctl chat --llm CMD [--session] [--store] [--protocol passive|json|regex]
+            [--max-calls N] [--budget N] [--source FILE ...] [--quiet]
+```
+
+Interactive memory-backed chat REPL. Each turn: FTS5 recall from the memory store, send context + question to the LLM, display the answer.
+
+**Stateless by default.** Each question sees only the memory store — no hidden conversation state.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--llm CMD` | *(required)* | LLM command (e.g. `"claude -p"`, `"ollama run granite3.1:2b"`) |
+| `--protocol` | `passive` | LLM output protocol. `passive` = single-pass; `json` = iterative refinement |
+| `--max-calls` | `1` | Max loop iterations per turn |
+| `--session` | off | Enable in-memory session context (sliding window of recent Q&A) |
+| `--history-turns` | `5` | Session window size (turns) |
+| `--session-budget` | `4000` | Session block character limit |
+| `--store` | off | Persist each answer as STM item |
+| `--source FILE...` | *(none)* | Pre-ingest files before starting |
+| `--tags` | `chat` | Tags for stored items (comma-separated) |
+
+**stdout purity:** answers go to stdout only. Prompt, banner, and hints go to stderr.
+
 ---
 
 ## Environment Variables
@@ -305,6 +407,18 @@ memctl search "" --json | jq -c '.[]'
 
 # Iterative recall-answer loop with trace
 memctl push "auth flow" --source docs/ | memctl loop "auth flow" --llm "claude -p" --trace
+
+# One-liner: inspect a folder (auto-mount + auto-sync)
+memctl inspect docs/
+
+# Inspect in JSON, pipe to jq for extension breakdown
+memctl inspect src/ --json | jq '.extensions'
+
+# Inspect without syncing (use cached state)
+memctl inspect docs/ --no-sync --json
+
+# Interactive chat with pre-ingested docs
+memctl chat --llm "claude -p" --source docs/ --session --store
 ```
 
 ---
@@ -359,14 +473,18 @@ Tool names use the `memory_*` prefix for drop-in compatibility with RAGIX.
 ```
 memctl/
 ├── types.py           Data model (MemoryItem, MemoryProposal, MemoryEvent, MemoryLink)
-├── store.py           SQLite + FTS5 + WAL backend (9 tables + schema_meta)
+├── store.py           SQLite + FTS5 + WAL backend (10 tables + schema_meta)
 ├── extract.py         Text extraction (text files + binary format dispatch)
 ├── ingest.py          Paragraph chunking, SHA-256 dedup, source resolution
 ├── policy.py          Write governance (30 patterns: secrets, injection, instructional)
 ├── config.py          Dataclass configuration
 ├── similarity.py      Stdlib text similarity (Jaccard + SequenceMatcher)
 ├── loop.py            Bounded recall-answer loop controller
-├── cli.py             9 CLI commands
+├── mount.py           Folder mount registration and management
+├── sync.py            Delta sync with 3-tier change detection
+├── inspect.py         Structural inspection and orchestration
+├── chat.py            Interactive memory-backed chat REPL
+├── cli.py             13 CLI commands
 ├── consolidate.py     Deterministic merge (Jaccard clustering, no LLM)
 ├── proposer.py        LLM output parsing (delimiter + regex)
 └── mcp/
@@ -375,7 +493,7 @@ memctl/
     └── server.py      FastMCP server entry point
 ```
 
-16 source files. ~5,300 lines. Zero compiled dependencies for core.
+20 source files. ~7,700 lines. Zero compiled dependencies for core.
 
 ### Memory Tiers
 
@@ -442,7 +560,7 @@ Deterministic, no-LLM merge pipeline:
 
 ## Database Schema
 
-Single SQLite file with WAL mode. 9 tables + 1 FTS5 virtual table:
+Single SQLite file with WAL mode. 10 tables + 1 FTS5 virtual table:
 
 | Table | Purpose |
 |-------|---------|
@@ -451,13 +569,14 @@ Single SQLite file with WAL mode. 9 tables + 1 FTS5 virtual table:
 | `memory_events` | Audit log (every read/write/consolidate) |
 | `memory_links` | Directional relationships (supersedes, supports, etc.) |
 | `memory_embeddings` | Reserved for RAGIX (empty in memctl) |
-| `corpus_hashes` | SHA-256 file dedup registry |
+| `corpus_hashes` | SHA-256 file dedup + mount metadata (mount_id, rel_path, ext, size_bytes, mtime_epoch, lang_hint) |
 | `corpus_metadata` | Corpus-level metadata |
 | `schema_meta` | Schema version, creation info |
 | `memory_palace_locations` | Reserved for RAGIX |
+| `memory_mounts` | Registered folder mounts (path, name, ignore patterns, lang hint) |
 | `memory_items_fts` | FTS5 virtual table for full-text search |
 
-Schema version is tracked in `schema_meta`. Current: `SCHEMA_VERSION=1`.
+Schema version is tracked in `schema_meta`. Current: `SCHEMA_VERSION=2`. Migration from v1 is additive (ALTER TABLE ADD COLUMN) and idempotent.
 
 ---
 
@@ -475,10 +594,11 @@ ragix memory stats --db /path/to/your/.memory/memory.db
 
 | Feature | memctl | RAGIX |
 |---------|--------|-------|
-| SQLite schema | Identical | Identical |
+| SQLite schema | Forward-compatible (RAGIX can open memctl DBs) | Superset |
 | Injection format | `format_version=1` | `format_version=1` |
 | MCP tool names | `memory_*` | `memory_*` |
 | FTS5 recall | Yes | Yes (+ hybrid embeddings) |
+| Folder mount + sync | Yes (v0.3+) | No |
 | Embeddings | No | Yes (FAISS + Ollama) |
 | LLM-assisted merge | No | Yes |
 | Graph-RAG | No | Yes |
@@ -532,7 +652,7 @@ pip install memctl[dev]
 pytest tests/ -v
 ```
 
-332 tests covering types, store, policy, ingest, text extraction, similarity, loop controller, forward compatibility, contracts, CLI (subprocess), and pipe composition.
+492 tests across 15 test files covering types, store, policy, ingest, text extraction, similarity, loop controller, mount, sync, inspect, chat, forward compatibility, contracts, CLI (subprocess), and pipe composition.
 
 ---
 

{memctl-0.2.1 → memctl-0.4.0}/memctl/__init__.py

@@ -7,7 +7,7 @@ Policy-governed, content-addressed, and forward-compatible with RAGIX.
 Author: Olivier Vitrac, PhD, HDR | olivier.vitrac@adservio.fr | Adservio
 """
 
-__version__ = "0.2.1"
+__version__ = "0.4.0"
 
 from memctl.types import (
     MemoryItem,