get-claudia 1.59.0 → 1.59.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to Claudia will be documented in this file.
 
+## 1.59.1 (2026-05-15)
+
+### Docs uplift
+
+Pure documentation. No code change.
+
+### Documentation
+- Added subpackage READMEs under `memory-daemon/claudia_memory/`: `services/`, `daemon/`, `extraction/`, `mcp/`. Each names the public entry points, lists the most relevant files, and captures the conventions a contributor needs to know before editing.
+- Expanded `CONTRIBUTING.md` with a "Your first PR" walkthrough covering the seven-step path from picking a starter issue to opening the PR.
+
+No user-visible behavior change.
+
+---
+
 ## 1.59.0 (2026-05-15)
 
 ### Removed

package/memory-daemon/claudia_memory/daemon/README.md

@@ -0,0 +1,16 @@
+# daemon/
+
+Long-running side of the memory daemon: scheduled background jobs and a local HTTP health endpoint. Only used when the daemon runs in standalone mode (`--standalone`); the MCP-server path (stdio transport, default) does not run these.
+
+## Where to look first
+
+| Concern | File | Notes |
+|---------|------|-------|
+| Scheduled background work | `scheduler.py` | APScheduler with three jobs: `daily_decay` at 02:00, `pattern_detection` every 6 hours, `full_consolidation` at 03:00. Optional `vault_sync` at 03:15 if `vault_sync_enabled` is set. |
+| Health endpoint | `health.py` | HTTP server bound to `localhost:3848`. The `/health` route is what the npm installer probes during Step 5 of install. The `/status` route powers the `memory_system_health` MCP tool. |
+
+## Conventions
+
+- **Bind localhost only.** Never `0.0.0.0`. The health server exposes internal state and is not auth-gated.
+- **New scheduled jobs go through the same path as existing ones.** Add to `scheduler.py`'s job registration. Don't spawn ad-hoc background threads from service modules.
+- **Service code stays in `services/`.** The daemon module is for *scheduling and exposing* that work, not implementing it. If you find yourself writing business logic here, move it to a service.

package/memory-daemon/claudia_memory/extraction/README.md

@@ -0,0 +1,16 @@
+# extraction/
+
+Pulling structured signal out of free-form text. Used by the remember pipeline (to identify which entities a memory is about) and by the ingest flow (to extract entities, commitments, and dates from longer documents).
+
+## Where to look first
+
+| Concern | File | Notes |
+|---------|------|-------|
+| Named-entity recognition | `entity_extractor.py` | Detects people, organizations, projects, concepts. Uses spaCy when the optional `[nlp]` extra is installed; falls back to pattern-based heuristics otherwise. |
+| Date and time parsing | `temporal.py` | Resolves relative phrases (e.g., "next Thursday") to absolute dates in the user's timezone. Used by commitment detection and event extraction. |
+
+## Conventions
+
+- **spaCy is optional.** Anything in `extraction/` must work without it. Test the no-spaCy path. If you require it, gate behind a clear `ImportError` message that tells the user to install `claudia-memory[nlp]`.
+- **Return structured results, never raw text.** Extractors emit typed dicts or dataclasses; the caller decides how to render them. This keeps the boundary clean and the call sites testable.
+- **Idempotent on re-extraction.** If a document is re-ingested, extractors must produce the same result. No hidden state.

package/memory-daemon/claudia_memory/mcp/README.md

@@ -0,0 +1,17 @@
+# mcp/
+
+The Model Context Protocol surface: how Claude Code talks to the memory daemon. Stdio transport, configured in the user's `.mcp.json` after install.
+
+## Where to look first
+
+| Concern | File | Notes |
+|---------|------|-------|
+| Tool registration | `server.py` | Single file defining all ~33 `memory_*` MCP tools. Each tool is a handler function paired with a JSONSchema-style parameter declaration. |
+
+## Conventions
+
+- **Tool names are a public API.** Never rename a `memory_*` tool. Users have skills and workflows that invoke them by name. Add new tools rather than renaming old ones.
+- **Tool docstrings are how Claude Code decides when to call.** Like skill descriptions, they need a clear verb, expected inputs, and example trigger phrases. Vague tool docs cause inconsistent invocation.
+- **Each tool is a thin wrapper.** The real work lives in `services/`. Handlers in `server.py` parse the MCP request, call into a service, format the response. No business logic here.
+- **Parameter aliases are supported for ergonomics.** `memory_about`, `memory_relate`, and `memory_recall` accept multiple parameter names (e.g., `entity` and `name`) so users can call them naturally. See PR #57 for the canonical example.
+- **Errors should be actionable.** When a handler raises, the error message reaches the user verbatim. Say what went wrong and what to try, not just "failed."

package/memory-daemon/claudia_memory/services/README.md

@@ -0,0 +1,25 @@
+# services/
+
+Business logic for the memory daemon. One module per concern. Every MCP tool exposed by `mcp/server.py` ultimately calls into a function here.
+
+## Where to look first
+
+| Concern | File | Public entry points |
+|---------|------|--------------------|
+| Write a memory, entity, or relationship | `remember.py` | `remember_fact`, `remember_entity`, `relate_entities`, `invalidate_memory` |
+| Recall memories or find entities | `recall.py` | `recall`, `recall_about`, `search_entities`, `deep_recall` |
+| Background decay + dedup + pattern detection | `consolidate.py` | `run_full_consolidation`, decay/dedup helpers, prediction lifecycle |
+| Entity type inference and naming | `entities.py` | `infer_entity_type` |
+| Memory and input validation rules | `guards.py` | `validate_memory`, `validate_entity`, `validate_relationship` |
+| File storage for filed source material | `filestore.py`, `documents.py` | `LocalFileStore`, document filing pipeline |
+| Provenance and audit trail | `audit.py` | source links, correction history |
+| Bulk historical fixes | `backfill.py` | one-shot maintenance utilities |
+| Compact session summaries for greeting | `context_builder.py` | `build_briefing_context` and friends |
+| Multi-document intake pipeline | `ingest.py` | the Extract-Then-Aggregate flow |
+| Obsidian vault projection | `vault_sync.py`, `canvas_generator.py` | PARA-layout write of entities, MOC canvases |
+
+## Conventions
+
+- **Soft-delete columns differ by table.** `memories.invalidated_at` vs. `entities.deleted_at`. Always check the schema before writing recall queries that filter "active" rows.
+- **Embedding storage is JSON text** (via `json.dumps`), not binary `struct.pack` blobs. Match this when writing new embedding paths.
+- Functions exported from a service module are the unit of testability. Tests for `recall.py` live at `tests/test_recall*.py` and call the module's public functions directly. Don't add internal coupling that bypasses those entry points.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-claudia",
-  "version": "1.59.0",
+  "version": "1.59.1",
   "description": "An AI assistant who learns how you work.",
   "keywords": [
     "claudia",

package/template-v2/.claude/manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.59.0",
-  "generated": "2026-05-15T13:12:53.476Z",
+  "version": "1.59.1",
+  "generated": "2026-05-15T13:14:19.001Z",
   "algorithm": "sha256",
   "files": {
     ".claude/rules/claudia-principles.md": "939e9720421628e7f2e4c8dfbaa4aeb9c1e18e8c6a5379cd6b772a6835b812e5",