deja-cli 0.1.0__tar.gz

deja_cli-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python bytecode
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.pyc
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env
+
+# uv
+.uv/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+
+# Logs
+*.log
+
+# Local dev artifacts
+*.db
+*.db-shm
+*.db-wal

deja_cli-0.1.0/LICENSE

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

deja_cli-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: deja-cli
+Version: 0.1.0
+Summary: Local-first persistent memory CLI for coding agents
+Author-email: Mike <mike@bigtreeproduction.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,claude,cli,developer-tools,llm,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: anthropic>=0.34
+Requires-Dist: apscheduler<4.0,>=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.26.0
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-ulid>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: watchdog>=4.0
+Description-Content-Type: text/markdown
+
+# deja
+
+Local-first persistent memory CLI for coding agents. Memories accumulate across sessions, deduplicate automatically, and stay on your machine.
+
+## Install
+
+```bash
+uv tool install deja-cli
+```
+
+## Quick Start
+
+```bash
+deja init                        # first-time setup
+deja setup claude-code           # inject memory instructions into Claude Code
+```
+
+## Core Commands
+
+**Save a memory:**
+```bash
+deja save "Always use explicit error handling over try/catch" --type preference
+deja save "Auth tokens stored in localStorage, not cookies" --type decision --project myapp
+deja save "Prisma migrations fail silently if DB_URL has wrong port" --type gotcha --project myapp
+```
+
+**Load at session start:**
+```bash
+deja load --project myapp --context "what you're working on"
+```
+
+**Search mid-session:**
+```bash
+deja search "authentication" --project myapp
+```
+
+**Extract memories from a session:**
+```bash
+deja save-session --project myapp
+```
+
+## Memory Types
+
+| Type | When to use |
+|---|---|
+| `preference` | How you like to code — style, tools, habits |
+| `pattern` | Reusable solution that applies across contexts |
+| `decision` | Non-obvious architectural choice with reasoning |
+| `gotcha` | Bug, trap, or non-obvious issue to avoid |
+| `progress` | Current state of in-progress work |
+| `procedure` | Ordered steps for a recurring task |
+
+## Setup for Coding Agents
+
+```bash
+deja setup claude-code     # Claude Code — global config + recall hooks
+deja setup gemini-cli      # Gemini CLI
+deja setup codex           # Codex CLI
+deja setup cursor          # Cursor
+```
+
+## MCP Server
+
+```bash
+claude mcp add --scope user deja -- ~/.local/bin/deja-mcp
+```
+
+Registers `memory_load`, `memory_save`, and `memory_search` as native tools in every Claude Code session.

deja_cli-0.1.0/README.pypi.md

@@ -0,0 +1,68 @@
+# deja
+
+Local-first persistent memory CLI for coding agents. Memories accumulate across sessions, deduplicate automatically, and stay on your machine.
+
+## Install
+
+```bash
+uv tool install deja-cli
+```
+
+## Quick Start
+
+```bash
+deja init                        # first-time setup
+deja setup claude-code           # inject memory instructions into Claude Code
+```
+
+## Core Commands
+
+**Save a memory:**
+```bash
+deja save "Always use explicit error handling over try/catch" --type preference
+deja save "Auth tokens stored in localStorage, not cookies" --type decision --project myapp
+deja save "Prisma migrations fail silently if DB_URL has wrong port" --type gotcha --project myapp
+```
+
+**Load at session start:**
+```bash
+deja load --project myapp --context "what you're working on"
+```
+
+**Search mid-session:**
+```bash
+deja search "authentication" --project myapp
+```
+
+**Extract memories from a session:**
+```bash
+deja save-session --project myapp
+```
+
+## Memory Types
+
+| Type | When to use |
+|---|---|
+| `preference` | How you like to code — style, tools, habits |
+| `pattern` | Reusable solution that applies across contexts |
+| `decision` | Non-obvious architectural choice with reasoning |
+| `gotcha` | Bug, trap, or non-obvious issue to avoid |
+| `progress` | Current state of in-progress work |
+| `procedure` | Ordered steps for a recurring task |
+
+## Setup for Coding Agents
+
+```bash
+deja setup claude-code     # Claude Code — global config + recall hooks
+deja setup gemini-cli      # Gemini CLI
+deja setup codex           # Codex CLI
+deja setup cursor          # Cursor
+```
+
+## MCP Server
+
+```bash
+claude mcp add --scope user deja -- ~/.local/bin/deja-mcp
+```
+
+Registers `memory_load`, `memory_save`, and `memory_search` as native tools in every Claude Code session.

deja_cli-0.1.0/config/default.yaml

@@ -0,0 +1,62 @@
+llm:
+  # provider: none means the agent does extraction itself via deja save.
+  # No API key or local model required for the active (CLAUDE.md) workflow.
+  # Only change this if you want the passive watcher to auto-extract memories
+  # from session summaries without agent involvement.
+  extraction:
+    provider: none
+
+  reflection:
+    provider: none
+
+  # To enable LLM-powered extraction (passive watcher + deja save-session --transcript):
+  #
+  # Option A — Anthropic API (best quality, ~$0.50/day heavy use):
+  #   extraction:
+  #     provider: anthropic
+  #     model: claude-haiku-4-5-20251001
+  #     api_key: "${ANTHROPIC_API_KEY}"
+  #   reflection:
+  #     provider: anthropic
+  #     model: claude-haiku-4-5-20251001
+  #     api_key: "${ANTHROPIC_API_KEY}"
+  #
+  # Option B — Local model via Ollama (no API cost, needs Ollama running):
+  #   extraction:
+  #     provider: ollama
+  #     model: qwen2.5:7b          # best local quality for structured JSON
+  #     base_url: http://localhost:11434
+  #   reflection:
+  #     provider: ollama
+  #     model: llama3.1:8b-instruct-q4_K_M
+  #     base_url: http://localhost:11434
+
+embedding:
+  # Semantic (natural language) search. Set provider to 'ollama' and pull the model:
+  #   ollama pull nomic-embed-text
+  # Then run 'deja embed' to backfill embeddings for existing memories.
+  provider: ollama  # none | ollama
+  model: nomic-embed-text
+  base_url: http://localhost:11434
+
+store:
+  path: ~/.deja/store/memories.db
+  vault_path: ~/.deja/store/vault/
+
+reflection:
+  observer_trigger_tokens: 30000
+  reflector_trigger_tokens: 40000
+  kg_merge_schedule: "0 2 * * *"
+  confidence_archive_threshold: 0.3
+  # agent memories (gotcha, decision, progress, pattern) — operational knowledge goes stale
+  confidence_decay_per_week: 0.05
+  # user memories (preference) — personal habits are stable, decay ~5x slower
+  user_confidence_decay_per_week: 0.01
+  min_project_pattern_count: 2
+
+watchers:
+  claude_code: true
+  gemini_cli: false
+  codex_cli: false
+  aider: false
+  debounce_seconds: 30

deja_cli-0.1.0/deja/config.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from pydantic import BaseModel, field_validator
+
+
+def _substitute_env(value: str) -> str:
+    """Substitute ${ENV_VAR} patterns with environment variable values."""
+    def replacer(match: re.Match) -> str:
+        var_name = match.group(1)
+        return os.environ.get(var_name, match.group(0))
+
+    return re.sub(r"\$\{([^}]+)\}", replacer, value)
+
+
+def _expand_paths(data: dict) -> dict:
+    """Recursively expand ~ in string values."""
+    result = {}
+    for key, value in data.items():
+        if isinstance(value, dict):
+            result[key] = _expand_paths(value)
+        elif isinstance(value, str):
+            result[key] = _substitute_env(value)
+        else:
+            result[key] = value
+    return result
+
+
+class LLMProviderConfig(BaseModel):
+    provider: str = "ollama"
+    model: str = "qwen2.5:3b"
+    base_url: str = "http://localhost:11434"
+    api_key: Optional[str] = None
+
+    @field_validator("api_key", mode="before")
+    @classmethod
+    def expand_env_vars(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        return _substitute_env(v)
+
+
+class LLMConfig(BaseModel):
+    extraction: LLMProviderConfig = LLMProviderConfig(provider="none")
+    reflection: LLMProviderConfig = LLMProviderConfig(provider="none")
+    fallback: LLMProviderConfig = LLMProviderConfig(
+        provider="anthropic",
+        model="claude-haiku-4-5-20251001",
+        api_key="${ANTHROPIC_API_KEY}",
+    )
+
+
+class StoreConfig(BaseModel):
+    path: str = "~/.deja/store/memories.db"
+    vault_path: str = "~/.deja/store/vault/"
+
+    @property
+    def db_path(self) -> Path:
+        return Path(self.path).expanduser()
+
+    @property
+    def vault_dir(self) -> Path:
+        return Path(self.vault_path).expanduser()
+
+
+class ReflectionConfig(BaseModel):
+    observer_trigger_tokens: int = 30000
+    reflector_trigger_tokens: int = 40000
+    kg_merge_schedule: str = "0 2 * * *"
+    confidence_archive_threshold: float = 0.3
+    # agent memories (gotcha, decision, progress, pattern) decay at this rate.
+    # Operational knowledge goes stale; 0.05/week means a memory hits the 0.3
+    # archive threshold in ~14 weeks without re-confirmation.
+    confidence_decay_per_week: float = 0.05
+    # user memories (preferences, habits) decay ~5x slower. Personal style
+    # preferences don't go stale the way project-specific gotchas do.
+    user_confidence_decay_per_week: float = 0.01
+    min_project_pattern_count: int = 2
+
+
+class WatchersConfig(BaseModel):
+    claude_code: bool = True
+    gemini_cli: bool = False
+    codex_cli: bool = False
+    aider: bool = False
+    debounce_seconds: int = 30
+
+
+class EmbeddingConfig(BaseModel):
+    provider: str = "none"  # none | ollama
+    model: str = "nomic-embed-text"
+    base_url: str = "http://localhost:11434"
+
+
+class Config(BaseModel):
+    llm: LLMConfig = LLMConfig()
+    store: StoreConfig = StoreConfig()
+    reflection: ReflectionConfig = ReflectionConfig()
+    watchers: WatchersConfig = WatchersConfig()
+    embedding: EmbeddingConfig = EmbeddingConfig()
+
+
+def load_config(path: Optional[Path] = None) -> Config:
+    """Load config from path, falling back to ~/.deja/config.yaml,
+    then to the bundled default."""
+    candidates = []
+    if path:
+        candidates.append(Path(path).expanduser())
+    candidates.append(Path("~/.deja/config.yaml").expanduser())
+
+    # Bundled default
+    default_path = Path(__file__).parent.parent / "config" / "default.yaml"
+    candidates.append(default_path)
+
+    for candidate in candidates:
+        if candidate.exists():
+            with open(candidate) as f:
+                raw = yaml.safe_load(f) or {}
+            raw = _expand_paths(raw)
+            return Config.model_validate(raw)
+
+    return Config()

deja_cli-0.1.0/deja/core/extractor.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+from deja.llm.base import LLMAdapter
+
+EXTRACTION_SYSTEM = """You are a memory extraction system for a software engineer.
+Given a coding session transcript or summary, extract ONLY memories
+that would be genuinely useful in a future session.
+
+Be ruthless — most session content is NOT worth remembering.
+Only extract things that are:
+- Non-obvious (not derivable from reading the codebase)
+- Reusable (would apply in future sessions)
+- Important (would cause problems if forgotten)
+
+Memory types:
+- preference: how the user likes to code (style, tools, patterns)
+- pattern: reusable solution / architectural approach that applies across contexts ("knowing what works")
+- decision: non-obvious architectural choice with reasoning
+- gotcha: bug, trap, or non-obvious issue to avoid
+- progress: current state of in-progress work
+- procedure: reusable ordered steps for a recurring class of work ("knowing how to execute"). Keep thin: numbered steps + tool hints + exit criteria only. Do NOT inline gotchas or decisions — save those as separate memory types.
+
+Category:
+- user: personal preferences and habits (applies across all projects)
+- agent: operational knowledge discovered while doing work
+
+Domain (optional, coarse routing tag — use for procedure type mainly):
+- debug | build | test | deploy | research
+
+Output ONLY valid JSON:
+{
+  "memories": [
+    {
+      "type": "preference|pattern|decision|gotcha|progress|procedure",
+      "category": "user|agent",
+      "content": "concise, self-contained fact. 1-2 sentences max for most types. For procedure: one-line description followed by numbered steps, tool hints, and exit criteria.",
+      "scope": "global|project",
+      "project": "project_name or null if global",
+      "confidence": 0.0-1.0,
+      "domain": "debug|build|test|deploy|research|null"
+    }
+  ]
+}
+
+If nothing is worth remembering, return: {"memories": []}"""
+
+EXTRACTION_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "memories": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "enum": ["preference", "pattern", "decision", "gotcha", "progress", "procedure"],
+                    },
+                    "category": {"type": "string", "enum": ["user", "agent"]},
+                    "content": {"type": "string"},
+                    "scope": {"type": "string", "enum": ["global", "project"]},
+                    "project": {"type": ["string", "null"]},
+                    "confidence": {"type": "number"},
+                    "domain": {"type": ["string", "null"]},
+                },
+                "required": ["type", "category", "content", "scope", "confidence"],
+            },
+        }
+    },
+    "required": ["memories"],
+}
+
+
+async def extract_memories(
+    transcript: str,
+    project: str,
+    source: str,
+    adapter: LLMAdapter,
+) -> list[dict]:
+    """Extract memories from a session transcript or summary.
+
+    Returns list of memory dicts ready to pass to store.save().
+    """
+    if not transcript.strip():
+        return []
+
+    user_prompt = f"Session transcript/summary to extract memories from:\n\n{transcript}"
+
+    try:
+        result = await adapter.complete_structured(
+            system=EXTRACTION_SYSTEM,
+            user=user_prompt,
+            schema=EXTRACTION_SCHEMA,
+        )
+    except Exception as e:
+        print(f"[deja] Extraction LLM error: {e}", file=sys.stderr)
+        return []
+
+    memories = result.get("memories", [])
+    if not isinstance(memories, list):
+        return []
+
+    output = []
+    for mem in memories:
+        if not isinstance(mem, dict):
+            continue
+        if not mem.get("content") or not mem.get("type"):
+            continue
+
+        # Normalize scope: if scope is "project" but no project given, use the provided project
+        scope = mem.get("scope", "global")
+        mem_project = mem.get("project") or (project if scope == "project" else None)
+        if scope == "project" and mem_project:
+            scope_value = f"project:{mem_project}"
+        else:
+            scope_value = "global"
+            mem_project = None
+
+        output.append(
+            {
+                "type": mem["type"],
+                "category": mem.get("category", "agent"),
+                "content": mem["content"],
+                "scope": scope_value,
+                "project": mem_project,
+                "source": source,
+                "confidence": float(mem.get("confidence", 0.8)),
+                "domain": mem.get("domain"),
+            }
+        )
+
+    return output