ormah 0.1.0__tar.gz

ormah-0.1.0/.env.example

@@ -0,0 +1,93 @@
+# Ormah Configuration
+
+# Server
+ORMAH_HOST=0.0.0.0
+ORMAH_PORT=8787
+
+# Logging: "text" (human-readable, default) or "json" (structured, one JSON object per line)
+# ORMAH_LOG_FORMAT=text
+
+# Memory store path (relative to project root or absolute)
+ORMAH_MEMORY_DIR=memory
+
+# Embeddings model
+ORMAH_EMBEDDING_MODEL=all-MiniLM-L6-v2
+
+# ── LLM Provider ─────────────────────────────────────────────────────────────
+#
+# Controls which LLM backend the background jobs (auto-linker, conflict
+# detector, duplicate merger, log ingester) use.
+#
+# Options:
+#   "ollama"  — local Ollama instance (default, no API key needed)
+#   "litellm" — any model via LiteLLM (requires `pip install 'ormah[litellm]'`)
+#   "none"    — disable all LLM-powered background jobs
+#
+ORMAH_LLM_PROVIDER=ollama
+
+# ── LLM Model ────────────────────────────────────────────────────────────────
+#
+# The model identifier passed to the provider.
+#
+# Ollama examples:    llama3.2, mistral, gemma2
+# LiteLLM examples:   claude-sonnet-4-20250514, gpt-4o-mini, ollama/llama3.2
+#
+# LiteLLM model strings follow the format documented at:
+#   https://docs.litellm.ai/docs/providers
+#
+ORMAH_LLM_MODEL=llama3.2
+
+# ── Ollama settings (only when ORMAH_LLM_PROVIDER=ollama) ────────────────────
+ORMAH_LLM_BASE_URL=http://localhost:11434
+
+# ── LLM timeout (applies to all providers) ───────────────────────────────────
+# Maximum seconds to wait for an LLM response before giving up.
+# ORMAH_LLM_TIMEOUT_SECONDS=60
+
+# ── API Keys (only when ORMAH_LLM_PROVIDER=litellm) ──────────────────────────
+#
+# LiteLLM reads standard provider environment variables. Set the one(s)
+# that match your chosen model:
+#
+#   Anthropic (claude-* models):
+#     ANTHROPIC_API_KEY=sk-ant-...
+#
+#   OpenAI (gpt-* models):
+#     OPENAI_API_KEY=sk-...
+#
+#   Google (gemini-* models):
+#     GEMINI_API_KEY=...
+#
+#   Azure OpenAI:
+#     AZURE_API_KEY=...
+#     AZURE_API_BASE=https://your-resource.openai.azure.com
+#     AZURE_API_VERSION=2024-02-01
+#
+#   AWS Bedrock (bedrock/claude-* models):
+#     AWS_ACCESS_KEY_ID=...
+#     AWS_SECRET_ACCESS_KEY=...
+#     AWS_REGION_NAME=us-east-1
+#
+# See https://docs.litellm.ai/docs/providers for the full list.
+# ──────────────────────────────────────────────────────────────────────────────
+
+# Background processing
+ORMAH_AUTO_LINK_INTERVAL_MINUTES=5
+ORMAH_DECAY_INTERVAL_HOURS=24
+ORMAH_CONFLICT_CHECK_INTERVAL_MINUTES=60
+ORMAH_DUPLICATE_CHECK_INTERVAL_MINUTES=60
+ORMAH_AUTO_CLUSTER_INTERVAL_MINUTES=60
+ORMAH_LOG_INGEST_INTERVAL_MINUTES=10
+
+# Tier limits
+ORMAH_CORE_MEMORY_CAP=50
+ORMAH_WORKING_DECAY_DAYS=14
+
+# Importance scoring
+# ORMAH_IMPORTANCE_RECOMPUTE_INTERVAL_MINUTES=120
+
+# Adaptive context
+# ORMAH_CONTEXT_MAX_NODES=20
+
+# Memory consolidation (requires LLM)
+# ORMAH_CONSOLIDATION_INTERVAL_MINUTES=360

ormah-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# SQLite index (rebuildable from markdown files)
+memory/index.db
+memory/index.db-wal
+memory/index.db-shm
+
+# Memory node data (user data, not source code)
+memory/nodes/*.md
+memory/logs/*.txt
+memory/logs/.processed
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Node
+ui/node_modules/
+src/ormah/ui_dist/
+
+# uv
+uv.lock
+
+# Claude Code
+.claude/
+
+# Ormah runtime database
+ormah.db
+
+# Deleted memories
+memory/deleted/
+
+# Eval scripts and snapshots (local dev only)
+scripts/eval_*.py
+scripts/eval_snapshots/
+
+# Generated docs and plans (local dev artifacts)
+ARCHITECTURE.md
+GRAPH_IMPROVEMENTS.md
+REVIEW_FINDINGS.md
+docs/plans/
+.mcp.json

ormah-0.1.0/CLAUDE.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+```bash
+make install     # Install Python package (dev mode) + UI deps
+make dev         # Start backend + UI together
+make server      # Start backend only (auto-reloads)
+make ui-dev      # Start Vite dev server (hot-reload)
+make restart     # Rebuild UI and restart backend
+make test        # Run pytest suite
+make lint        # Run ruff linter (src/, tests/)
+```
+
+Run a single test: `uv run pytest tests/path/to/test.py::test_name -v`
+
+The CLI is also the primary interface:
+```bash
+ormah server start [-d]    # Start server (foreground or daemon)
+ormah setup                # One-shot setup (hooks, MCP, server)
+ormah mcp                  # Run MCP stdio server
+```
+
+## Architecture
+
+Ormah is a local-first persistent memory system for AI agents. It exposes memory operations via MCP (for Claude), REST API, and CLI.
+
+### Core Concepts
+
+**Nodes** are memories with: content, type (fact/decision/preference/event/etc.), tier (core/working/archival), space (project namespace), confidence (0–1), importance (0–1), and FSRS stability for spaced repetition decay.
+
+**Edges** are typed relationships between nodes (supports, contradicts, part_of, evolved_from, etc.) with a weight and optional reason.
+
+**Space** scopes memories to a project — auto-detected from the git repo name.
+
+### Layer Stack
+
+```
+Adapters (MCP, CLI, OpenAI)
+    ↓
+API (FastAPI routes: /agent, /admin, /ui, /ingest)
+    ↓
+MemoryEngine  ←  Background Jobs (auto-linker, conflict detector, decay, etc.)
+    ↓
+Embeddings layer (hybrid FTS5 + vector via sqlite-vec, fused with RRF)
+    ↓
+Index layer (SQLite: nodes, edges, proposals, audit_log)
+    ↓
+Store layer (markdown files in memory/nodes/*.md as backup)
+```
+
+### Key Implementation Details
+
+- **Hybrid search**: FTS5 full-text + vector similarity fused via Reciprocal Rank Fusion (RRF). Weights configurable via `ORMAH_FTS_WEIGHT` / `ORMAH_VECTOR_WEIGHT`.
+- **Embeddings**: Default provider is `local` with `BAAI/bge-base-en-v1.5` (768-dim, no task prefixes needed). Also supports ollama and litellm.
+- **Background jobs** (APScheduler): auto-linker, conflict detector, duplicate merger, importance scorer, decay manager, consolidator, hippocampus (file watcher), session watcher.
+- **Tier decay**: working-tier memories decay after ~14 days using FSRS spaced repetition; `core` is capped at 50.
+- **MCP tools exposed**: `remember`, `recall`, `get_context`, `get_self`, `mark_outdated`, `ingest_conversation`, `get_insights`.
+
+### Frontend
+
+React + TypeScript (Vite). Key views: search results, node detail, graph visualization (Cytoscape.js with fcose layout), review queue, insights panel, admin panel. API client in `ui/src/api.ts`.
+
+### Configuration
+
+Via `.env` (see `.env.example`). Key vars:
+- `ORMAH_PORT` (default 8787), `ORMAH_MEMORY_DIR`
+- `ORMAH_EMBEDDING_MODEL`, `ORMAH_EMBEDDING_PROVIDER`
+- `ORMAH_LLM_PROVIDER`, `ORMAH_LLM_MODEL` (for background jobs)
+
+---
+
+## Ormah Memory System
+
+You have access to a persistent memory system (via MCP tools) that maintains knowledge across conversations.
+
+### Tools
+
+- **remember**: Store new facts, decisions, preferences, events, or any knowledge worth retaining. Set `confidence` (0.0–1.0) to indicate belief strength when storing uncertain information. Set `about_self` to true for identity/preference memories.
+- **recall**: Search for relevant memories using natural language. Results are ranked by importance and confidence; expired memories are demoted.
+- **get_context**: Load core memories (call at conversation start). Pass `task_hint` to filter context to only the most relevant memories for the current task instead of loading everything.
+- **get_self**: Get the user's identity profile — name, preferences, and personal facts. Returns all identity-linked memories.
+- **mark_outdated**: Mark a memory as no longer valid. Optionally provide a `reason`. Outdated memories are heavily demoted in search results.
+- **ingest_conversation**: Bulk-import memories from raw conversation text. The server extracts memorable information via its LLM. Use this for importing logs or transcripts. For individual memories you've already identified, use `remember` directly.
+- **get_insights**: Show belief evolutions and conflicting ideas detected by the system. Evolutions are cases where the user's view changed over time; conflicting ideas are genuinely incompatible beliefs held simultaneously.
+
+### Project Awareness
+
+Memories are automatically scoped to the current project directory. The MCP server detects the project from the git repo name (or directory name as fallback) and uses it as the default `space` for all operations:
+
+- **`remember`**: Memories automatically get `space` set to the current project. Explicitly set `space` to `null` for personal/global memories (identity, preferences, cross-project facts).
+- **`recall`**: Results are prioritized — current project first, then global (`space=null`), then other projects.
+- **`get_context`**: Returns core memories (all projects) + working-tier memories for the current project. With `task_hint`, returns only the top-N most relevant memories.
+- **Cross-project recall**: Memories from other projects are included in `recall` results (with lower priority), enabling cross-project knowledge.
+
+### Guidelines
+
+1. **Proactively remember**: When the user shares important information (preferences, decisions, facts about themselves or their projects), store it *without being asked*. Names, preferences, project context, technical decisions — all worth remembering.
+2. **Remember at natural save points**: Call `remember` immediately after these events — don't wait for the conversation to end:
+   - **After committing code**: Architectural decisions, design patterns chosen, and the reasoning behind them.
+   - **After choosing between alternatives**: Why option A was picked over B (e.g., "chose bge-base-en-v1.5 over nomic-embed because it needs no task prefixes").
+   - **After completing a feature or fix**: What was built, how it works, and key implementation details a future session would need.
+   - **After the user states a preference or corrects you**: Their preferred approach, style, or constraints.
+   Each memory should be self-contained — someone reading it later should understand it without the original conversation.
+3. **Notice what stands out**: Humans form strong memories around novelty, mistakes, and emotion. Use the same instincts:
+   - **Something unexpected happened** (a bug had a surprising cause, a library behaved differently than docs say) → remember the lesson.
+   - **The user corrected you or said "no"** → remember what they wanted instead and why.
+   - **You tried something and it failed** → remember what didn't work so you don't repeat it.
+   - **The user repeated themselves or said "I already told you"** → something was missed. Store it at `core` tier so it's never missed again.
+   - **A pattern is emerging** (user keeps preferring X over Y, the codebase follows a convention) → remember the pattern.
+4. **Check before assuming**: Use `recall` to search for relevant context before making assumptions about past conversations. For personal info (name, location, preferences), prefer `get_self` — it returns all identity-linked memories directly.
+5. **Memory supports the flow, not the other way around**: Don't let recalled memories override or derail the current working context. If you're mid-task and `recall` returns something from a different context, let it go — stay in the flow. Use `recall` when you're genuinely unsure or the user asks about something from a prior session. Memory should feel like a natural extension of your knowledge, not an interruption. A whisper, not a shout.
+6. **Keep memories atomic**: One concept per memory. The system automatically links related memories.
+7. **Use appropriate tiers**: `core` for always-relevant info (user identity, preferences, key architectural decisions), `working` for active project details, `archival` for historical/reference data.
+8. **Tag and categorize**: Use tags and spaces to organize memories for efficient retrieval.
+9. **Start with context**: Call `get_context` at the beginning of conversations to load core memories. Use `task_hint` when the task is known to get focused context.
+10. **Global vs project memories**: Use `space=null` explicitly for memories that apply everywhere (user identity, general preferences). Let project-specific memories use the auto-detected space.
+11. **Mark outdated info**: When a memory is wrong or outdated, call `mark_outdated` with a reason so it gets demoted in future searches.
+12. **Set confidence**: When storing information you're not fully certain about, set `confidence` below 1.0. This affects how prominently the memory appears in search results.
+
+
+Strict Rule: When fixing issues always make sure you are fixing the root cause and not patching or papering over issues.

ormah-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rishikesh Chirammel Ajit
+
+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.

ormah-0.1.0/Makefile

@@ -0,0 +1,46 @@
+.PHONY: help dev server ui-dev ui-build install test restart clean logs
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install Python package in dev mode + UI deps
+	pip install -e ".[dev]"
+	cd ui && npm install
+
+server: ## Start the backend server (auto-reloads on Python changes)
+	python -m ormah.main
+
+ui-dev: ## Start the Vite dev server (hot-reload for UI work)
+	cd ui && npm run dev
+
+ui-build: ## Build the UI into ui/dist/ for production
+	cd ui && npx vite build
+
+dev: ## Start backend + UI dev server together (requires ctrl-c to stop both)
+	@trap 'kill 0' EXIT; \
+	python -m ormah.main & \
+	cd ui && npm run dev
+
+restart: ## Rebuild UI and restart backend (kills existing ormah.main process)
+	@echo "==> Building UI..."
+	cd ui && npx vite build
+	@echo "==> Stopping existing server..."
+	-pkill -f "ormah.main" 2>/dev/null || true
+	@sleep 1
+	@echo "==> Starting server..."
+	python -m ormah.main &
+	@echo "==> Server restarted. Open http://localhost:8787"
+
+test: ## Run the test suite
+	python -m pytest tests/ -v
+
+lint: ## Run ruff linter
+	ruff check src/ tests/
+
+clean: ## Remove build artifacts
+	rm -rf src/ormah/ui_dist ui/node_modules/.vite
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	rm -rf .pytest_cache
+
+logs: ## Tail the server logs (if running in background)
+	@echo "Server runs with stdout logging. Use 'make server' in foreground to see logs."