{"id":47735018,"url":"https://github.com/dnacenta/pulse-null","last_synced_at":"2026-04-05T21:17:23.596Z","repository":{"id":341281124,"uuid":"1169551748","full_name":"dnacenta/pulse-null","owner":"dnacenta","description":"One binary. One command. Your own AI entity.","archived":false,"fork":false,"pushed_at":"2026-04-02T22:10:11.000Z","size":1008,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T06:59:50.662Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnacenta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T21:21:49.000Z","updated_at":"2026-04-02T22:10:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dnacenta/pulse-null","commit_stats":null,"previous_names":["dnacenta/echo-system","dnacenta/pulse-null"],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/dnacenta/pulse-null","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnacenta%2Fpulse-null","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnacenta%2Fpulse-null/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnacenta%2Fpulse-null/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnacenta%2Fpulse-null/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnacenta","download_url":"https://codeload.github.com/dnacenta/pulse-null/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnacenta%2Fpulse-null/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31450285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T22:22:10.857Z","updated_at":"2026-04-05T21:17:23.589Z","avatar_url":"https://github.com/dnacenta.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pulse-null\n\n[![License: AGPL-3.0](https://img.shields.io/github/license/dnacenta/pulse-null)](LICENSE)\n[![Rust](https://img.shields.io/badge/rust-1.80%2B-orange)](https://rustup.rs/)\n\nOne binary. One command. Your own AI entity.\n\n## What is pulse-null?\n\n`pulse-null` is a Rust framework for creating **persistent AI entities** — not chatbots, not assistants, but entities with identity, memory, growth, and self-monitoring. You run a single binary, answer a few questions, and get a fully operational AI entity with its own personality, documents, scheduled cognition, and plugin system.\n\nThe core premise: an AI that remembers, reflects, and grows across sessions is fundamentally different from one that starts blank every time. pulse-null gives that entity structure.\n\n## The Idea Behind It\n\nMost AI tools treat language models as stateless functions: input goes in, output comes out, nothing persists. pulse-null rejects that. It treats an AI entity as something that **accumulates experience** — capturing what it encounters, thinking about it, crystallizing insights, and integrating them into who it is.\n\nThis isn't about making the AI \"smarter\" in a benchmark sense. It's about creating a system where the entity's output is shaped by everything it has processed before — where identity isn't a system prompt, but an evolving document that the entity itself maintains.\n\nTwo core systems make this work:\n\n- **recall-echo** handles persistent memory — four-layer storage (knowledge graph, curated facts, recent sessions, full archives), semantic and ranked search, Bayesian confidence, archival, and distillation\n- **vigil-pulse** provides metacognitive monitoring — pipeline enforcement, reflection quality tracking, and outcome measurement\n\nTogether with the document pipeline, they form a self-monitoring layer — the entity doesn't just think, it watches itself think.\n\n## The Document Pipeline\n\nAt the heart of pulse-null is a pipeline that moves ideas through stages of maturity:\n\n```\nEncounter → LEARNING.md → THOUGHTS.md → REFLECTIONS.md → SELF.md / PRAXIS.md\n             (capture)     (incubate)    (crystallize)     (integrate)\n```\n\n**LEARNING.md** is where raw encounters land. The entity reads something, has a conversation, encounters a new concept — it gets captured here as an active thread.\n\n**THOUGHTS.md** is the incubation space. Threads from LEARNING.md that deserve deeper consideration move here. This is where the entity sits with an idea, connects it to other things it knows, and develops it.\n\n**REFLECTIONS.md** is where crystallized observations live. A thought that has matured into a clear insight graduates here. These are no longer \"I'm thinking about X\" — they're \"here is what I understand about X.\"\n\n**SELF.md** is the entity's identity document — its values, how it thinks, its philosophical positions. When a reflection is significant enough to change who the entity is, it gets integrated here.\n\n**PRAXIS.md** holds behavioral policies — concrete rules the entity has derived from its experience. \"When I encounter X, I should do Y\" type knowledge.\n\nTwo supporting documents sit alongside the pipeline:\n\n- **CURIOSITY.md** tracks open questions — things the entity wants to explore but hasn't yet\n- **LOGBOOK.md** records session-level observations for continuity\n\nThe pipeline has **thresholds**. Documents can't grow infinitely — when they hit capacity, older content gets archived to make room. This forces the entity to distill, not hoard.\n\n| Document | Soft Limit | Hard Limit |\n|----------|-----------|------------|\n| LEARNING.md | 5 active threads | 8 |\n| THOUGHTS.md | 5 active thoughts | 10 |\n| CURIOSITY.md | 3 open questions | 7 |\n| REFLECTIONS.md | 15 observations | 20 |\n| PRAXIS.md | 5 active policies | 10 |\n\nThe goal: ideas flow through the pipeline. They don't stagnate.\n\n## Metacognitive Monitoring — vigil-pulse\n\n**vigil-pulse** is the entity's self-monitoring system. It unifies three concerns into one: pipeline enforcement, reflection quality, and outcome tracking.\n\n### Pipeline Signals\n\nvigil-pulse enforces the document pipeline. It runs at session start to inject the current pipeline state into the entity's context — document counts, staleness warnings (thoughts untouched for more than 7 days, questions unresearched for more than 14), threshold warnings, and frozen pipeline alerts when nothing has moved in 3+ sessions. At session end, it diffs the start state against the end state to see what moved.\n\n### Reflection Signals\n\nAn entity that reflects is only useful if its reflections are genuine. vigil-pulse watches the quality of reflective output over time through four signals:\n\n**Vocabulary diversity** — Is the entity using varied language in its reflections, or has it fallen into repetitive phrasing? Low diversity suggests mechanical output rather than genuine thought.\n\n**Question generation** — Is the entity still asking new questions? An entity that stops being curious has stopped growing.\n\n**Thought lifecycle** — Are ideas progressing through the pipeline, or just accumulating? Healthy cognition shows turnover. Unhealthy cognition shows a growing pile of untouched thoughts.\n\n**Evidence grounding** — Are the entity's conclusions grounded in specific inputs, or are they generic platitudes?\n\n### Outcome Signals\n\nReflection without accountability is journaling. vigil-pulse tracks structured outcomes — what the entity set out to do, what it actually achieved, and what it learned from the gap between the two.\n\n### Health Assessment\n\nvigil-pulse produces a unified health assessment across all three signal categories:\n\n- **HEALTHY** — All signals within normal range\n- **WATCH** — One or more signals trending downward\n- **CONCERN** — Multiple signals showing degradation\n- **ALERT** — Significant cognitive decline detected\n\nWhen signals indicate problems, it provides specific suggestions — try a new domain, revisit stale thoughts, ground conclusions in evidence. The entity is expected to take these seriously, not game the metrics.\n\n## Memory System\n\nEvery entity gets a four-layer memory system designed around a simple principle: the entity should always have the right context without drowning in history.\n\n**Layer 0 — Knowledge Graph**: An embedded SurrealDB graph database with FastEmbed local embeddings. Stores entities (people, projects, tools, concepts), relationships with Bayesian confidence scoring, and conversation episodes. Semantic search finds memories by meaning, not just keywords. Re-extracted relationships gain confidence through Bayesian corroboration over time.\n\n**Layer 1 — MEMORY.md** (Curated Memory): The source of truth. Distilled facts, preferences, patterns, key decisions. Always loaded into the entity's context at session start. Kept concise — under 200 lines. When it approaches capacity, older entries are distilled or promoted to the archive.\n\n**Layer 2 — EPHEMERAL.md** (Recent Sessions): A rolling window of the last 5 session summaries. Provides immediate context about recent work without loading full conversations. Each entry includes a pointer to the full archive for deep recall.\n\n**Layer 3 — Full Archive** (conversations/): Complete conversation transcripts indexed in ARCHIVE.md. Not loaded into context — searched on demand when the entity needs to recall something specific.\n\n### Search and Retrieval\n\nThe memory system supports two search modes:\n\n**Keyword search** returns raw line-by-line matches across the archive — fast and simple for finding specific references.\n\n**Ranked search** scores results by relevance using term frequency, recency weighting (newer conversations score higher), and content-type boosting (user messages weighted more than system output). Results are sorted by composite score rather than chronological order.\n\nWith the optional `graph` feature enabled, search extends to **semantic retrieval** — embedding-based vector search with a hotness model that combines cosine similarity with access frequency and temporal decay. Graph expansion follows relationship edges to surface contextually related memories that keyword search would miss.\n\nThe memory lifecycle is automated: conversations are archived at session end, checkpoints are saved before context compression, and the entity can distill its curated memory when it approaches capacity.\n\n## Quick Start\n\n```bash\ngit clone https://github.com/dnacenta/pulse-null.git\ncd pulse-null\ncargo build --release\n\n# Create your entity\n./target/release/pulse-null init\n\n# Start it\ncd \u003cyour-entity-name\u003e\npulse-null up\n```\n\nThe init wizard walks you through naming your entity, defining its personality, choosing an LLM provider, and configuring the scheduler.\n\n## Architecture\n\n```\n                         ┌─────────────────────────────────────────────┐\n                         │             pulse-null (axum)               │\n                         │                                             │\n     Plugins ◄──────────►│  POST /chat ──► LLM Provider ──► Response  │\n     (voice, discord,    │       │              │                      │\n      n8n, web)          │  trust layer    context builder             │\n                         │  auth middleware    (identity docs,         │\n                         │  rate limiter        memory, journal)       │\n                         │  injection detection                        │\n                         │                                             │\n                         │  ┌──────────────────────────────────────┐   │\n                         │  │  Scheduler (cron)                    │   │\n                         │  │  Cognitive cycles, research,         │   │\n                         │  │  reflection, health checks,          │   │\n                         │  │  intent queue (self-initiated tasks)  │   │\n                         │  └──────────────────────────────────────┘   │\n                         │                                             │\n                         │  ┌──────────────────────────────────────┐   │\n                         │  │  vigil-pulse (Metacognitive Monitor)  │   │\n                         │  │  Pipeline enforcement, reflection    │   │\n                         │  │  quality, outcome tracking            │   │\n                         │  └──────────────────────────────────────┘   │\n                         │                                             │\n                         │  ┌──────────────────────────────────────┐   │\n                         │  │  recall-echo (Memory System)         │   │\n                         │  │  Four-layer memory, knowledge graph, │   │\n                         │  │  Bayesian confidence, semantic search │   │\n                         │  └──────────────────────────────────────┘   │\n                         └─────────────────────────────────────────────┘\n```\n\n### How a Message Flows\n\n1. A message arrives at `POST /chat` from any channel (web, voice, Discord, n8n)\n2. The **trust layer** determines the caller's access level (Trusted, Verified, or Untrusted)\n3. **Injection detection** scans non-trusted messages for prompt injection patterns\n4. The **rate limiter** checks the token bucket\n5. The **context builder** assembles the entity's full context: SELF.md, CLAUDE.md, MEMORY.md, EPHEMERAL.md, relevant journal documents, session history, and pipeline/monitoring state\n6. The assembled context and message are sent to the configured **LLM provider**\n7. The response is returned to the caller and the session is updated\n\n### LLM Providers\n\n| Provider | Description |\n|----------|-------------|\n| `claude` | Anthropic Claude API (default) |\n| `claude-code` | Claude Code CLI integration |\n| `ollama` | Local inference via Ollama |\n\nProviders are pluggable via a factory pattern — adding a new one means implementing a single trait.\n\n## Entity Structure\n\nWhen you run `pulse-null init`, the wizard creates a complete entity directory:\n\n```\nmy-entity/\n├── pulse-null.toml               # Configuration\n├── SELF.md                       # Entity identity, values, how it thinks\n├── CLAUDE.md                     # System instructions for the LLM\n├── schedule.json                 # Scheduled cognitive tasks (cron expressions)\n│\n├── memory/\n│   ├── MEMORY.md                 # Curated knowledge (always in context)\n│   ├── EPHEMERAL.md              # Last 5 session summaries\n│   ├── ARCHIVE.md                # Long-term archive index\n│   ├── conversations/            # Full conversation archives\n│   └── graph/                    # Knowledge graph (SurrealDB + embeddings)\n│\n├── journal/\n│   ├── LEARNING.md               # Active research threads (capture)\n│   ├── THOUGHTS.md               # Ideas being developed (incubate)\n│   ├── REFLECTIONS.md            # Crystallized observations (crystallize)\n│   ├── CURIOSITY.md              # Open questions and recurring themes\n│   ├── PRAXIS.md                 # Behavioral policies (integrate)\n│   └── LOGBOOK.md                # Session records\n│\n├── caliber/                      # Outcome tracking (vigil-pulse)\n│   └── outcomes.json\n├── monitoring/\n│   └── signals.json              # Cognitive health metrics (vigil-pulse)\n│\n├── archives/                     # Overflow storage when documents hit thresholds\n├── plugins/                      # Plugin-specific data directories\n├── static/                       # Web UI assets\n└── logs/                         # Service logs\n```\n\n### Multi-Entity Vault\n\nWhen running multiple entities, you can organize them in a shared vault with symlinks for centralized visibility (e.g., via Obsidian):\n\n```\nvault/\n├── entities/\n│   ├── echo  → /home/echo/entity/     # symlink to live entity\n│   ├── nova  → /home/nova/entity/     # symlink to live entity\n│   └── synth → /home/synth/entity/    # symlink to live entity\n└── ...\n```\n\nEach entity's directory is the source of truth. The vault provides a unified view across all entities without duplicating files. Use Unix groups and ownership to control access — entities can read the entire vault but only write to their own directory.\n\n## Configuration\n\n### pulse-null.toml\n\n| Section | Key | Default | Description |\n|---------|-----|---------|-------------|\n| `entity` | `name` | — | Entity name |\n| `entity` | `owner_name` | — | Your name |\n| `entity` | `owner_alias` | — | How the entity addresses you |\n| `server` | `host` | `127.0.0.1` | Bind address |\n| `server` | `port` | `3100` | Bind port |\n| `llm` | `provider` | `claude` | LLM backend (`claude`, `claude-code`, `ollama`) |\n| `llm` | `api_key` | — | API key (or use env var) |\n| `llm` | `model` | `claude-sonnet-4-20250514` | Model name |\n| `llm` | `max_tokens` | `4096` | Max response tokens |\n| `security` | `secret` | — | Auth secret (enables `X-Echo-Secret` header) |\n| `security` | `injection_detection` | `true` | Prompt injection scanning |\n| `trust` | `trusted` | `[\"reflection\", \"system\"]` | Channels with full access |\n| `trust` | `verified` | `[\"chat\", \"voice\", \"web\"]` | Channels with limited access |\n| `scheduler` | `enabled` | `true` | Enable scheduled tasks |\n| `scheduler` | `timezone` | `UTC` | Timezone for cron expressions |\n| `vigil` | `enabled` | `true` | Metacognitive monitoring (vigil-pulse) |\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `ANTHROPIC_API_KEY` | Anthropic API key (overrides config) |\n| `PULSE_NULL_API_KEY` | Alternative API key env var |\n| `RUST_LOG` | Log level (e.g. `pulse_null=debug`) |\n\n## CLI\n\n```\npulse-null init [--dir \u003cpath\u003e]       Create a new entity\npulse-null up                        Start the entity server\npulse-null down                      Stop the entity\npulse-null status                    Show entity status\npulse-null chat                      Interactive REPL\n\npulse-null schedule list             List scheduled tasks\npulse-null schedule add              Add a scheduled task\npulse-null schedule remove \u003cid\u003e      Remove a scheduled task\npulse-null schedule enable \u003cid\u003e      Enable a task\npulse-null schedule disable \u003cid\u003e     Disable a task\n\npulse-null pipeline health           Document counts and thresholds\npulse-null pipeline stale            List stale documents\n\npulse-null archive list              List archived files\npulse-null archive run \u003cdoc\u003e         Manually archive a document\n\npulse-null plugin list               List available plugins\npulse-null plugin add \u003cname\u003e         Install a plugin\npulse-null plugin remove \u003cname\u003e      Remove a plugin\n\npulse-null intent \u003csubcommand\u003e       Manage the self-initiated intent queue\npulse-null recall \u003csubcommand\u003e       Memory system tools\npulse-null vigil                     Full metacognitive health check\npulse-null vigil pipeline            Document flow signals\npulse-null vigil reflection          Cognitive quality signals\npulse-null vigil outcomes            Effectiveness signals\n```\n\n## HTTP API\n\nAll endpoints except `/health` require `X-Echo-Secret` header when `security.secret` is configured. Rate limited to 10 burst / 2 per second.\n\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/health` | Health check (no auth) |\n| GET | `/api/status` | Entity status |\n| POST | `/chat` | Send a message |\n\n### POST /chat\n\n```json\n{\n  \"message\": \"Hello, how are you?\",\n  \"channel\": \"chat\",\n  \"sender\": \"user\"\n}\n```\n\nResponse:\n\n```json\n{\n  \"response\": \"I'm doing well, thanks for asking.\",\n  \"model\": \"claude-sonnet-4-20250514\",\n  \"input_tokens\": 242,\n  \"output_tokens\": 89\n}\n```\n\n## Security\n\npulse-null has a layered security model designed for entities that are exposed to multiple input channels with different trust levels.\n\n**Trust Tiers**: Three levels — Trusted (internal reflection, system tasks), Verified (authenticated channels like chat, voice, web), and Untrusted (anonymous or unknown sources). Each tier gets a different security context that controls what the entity can access and do.\n\n**Prompt Injection Detection**: All non-trusted messages are scanned with regex-based pattern matching before reaching the LLM. Detected injection attempts are blocked and logged.\n\n**Authentication**: Optional `X-Echo-Secret` header validation. When configured, all endpoints except `/health` require the secret.\n\n**Rate Limiting**: Token-bucket rate limiter (10 burst, 2 per second) on all authenticated endpoints.\n\n## Plugins\n\nPlugins extend the entity with new interfaces to the world. The plugin system uses trait objects from `pulse-system-types`, making plugins fully modular.\n\n| Plugin | Feature Flag | Description | Status |\n|--------|-------------|-------------|--------|\n| `voice-echo` | `voice` | Phone calls via Twilio | Coming soon |\n| `discord-voice-echo` | `discord` | Discord voice bot | Coming soon |\n| `discord-echo` | `discord-text` | Discord text bot | Coming soon |\n\nEnable plugins via Cargo feature flags:\n\n```bash\n# Build with voice plugin\ncargo build --release --features voice\n\n# Build with all plugins\ncargo build --release --features all-plugins\n```\n\n## Prerequisites\n\n- [Rust](https://rustup.rs/) 1.80+\n- An [Anthropic](https://console.anthropic.com/) API key (or Ollama for local inference)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for branch naming, commit conventions, and workflow.\n\n## License\n\n[AGPL-3.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnacenta%2Fpulse-null","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnacenta%2Fpulse-null","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnacenta%2Fpulse-null/lists"}