HLJ
← Back to projects

Personal Project

Nous

June 2026 — Present

A local-first personal self-knowledge system that preserves writings, reflections, images, and project artifacts as source evidence, turns them into reviewable Obsidian records and knowledge-graph relationships, and exposes a provenance-aware core for future AI agents, memory interfaces, and personal knowledge applications.

GitHub →

Overview

Nous is a local-first personal self-knowledge system designed to turn raw life data into a structured, source-backed model of a person over time.

The project began from a question: what would it take to build a personal data resource rich enough that future AI systems could understand not just isolated notes, but a person's memories, values, beliefs, decisions, projects, relationships, contradictions, questions, and changes over time?

Instead of starting with a chatbot, vector database, or visualization layer, I designed Nous around a more fundamental requirement: build the underlying personal knowledge base first, and make that data portable, auditable, provenance-backed, reviewable, and safe for future agents to consume.

Nous uses an Obsidian-compatible Markdown vault as its primary storage and review layer. Raw source material is preserved before interpretation. Generated notes and graph relationships enter a non-canonical inbox. Human review determines what becomes trusted knowledge. Reviewed records can then be projected into graph JSON, human-readable Nous reports, and bounded read operations for future AI agents.

The current implementation includes:

The longer-term goal is for Nous to become a personal information substrate that can support applications such as memory chat, self-visualization, longitudinal reflection, decision support, personal AI agents, and eventually a consent-based interpersonal knowledge graph.

Problem

Most personal knowledge systems store documents, not an actual model of the person who created them.

Notes may contain important memories, beliefs, projects, decisions, and reflections, but the relationships between them are usually implicit. AI assistants can search documents, but they often lack durable information about:

This becomes especially problematic when building long-lived personal AI systems.

A model may confidently transform a tentative observation into a permanent "fact." Summaries can gradually drift away from original evidence. Generated interpretations can contaminate a knowledge base until it becomes impossible to distinguish the person's actual words from accumulated model inference.

Nous addresses this by treating provenance and review state as first-class parts of the data model.

The system separates four fundamentally different layers:

  1. Raw evidence — what actually entered the system.
  2. Generated candidates — what software or an agent proposes.
  3. Human-reviewed knowledge — what the user has accepted.
  4. Derived outputs — regenerable reports, graphs, and views.

The central design principle is that an AI system should be able to help organize a person's knowledge without silently becoming the authority on who that person is.

Product Thesis

Nous is intentionally not designed around a chatbot as the core product.

The core product is the high-quality personal data resource underneath future intelligent interfaces.

The project follows several principles:

This architecture makes the resulting personal knowledge base useful independently of any particular LLM, application framework, or AI provider.

My Role

I designed and built Nous as an independent project across product architecture, data modeling, local tooling, agent safety, and knowledge-system design.

My work includes:

System Architecture

At a high level, Nous follows this lifecycle:

Reflections / writings / images / project artifacts
                        ↓
                  Raw evidence
           vault/00_raw_artifacts/
                        ↓
             Conservative processing
                        ↓
              Agent candidate inbox
           vault/01_agent_inbox/
                        ↓
                   Human review
                 ↙             ↘
        Reviewed notes       Canonical model
       vault/02_notes/       vault/03_canonical_model/
                 ↘             ↙
                 Trusted records
                        ↓
          ┌─────────────┴─────────────┐
          ↓                           ↓
   Knowledge graph               Nous report
      JSON export                Markdown view
          └─────────────┬─────────────┘
                        ↓
                 Nous Core reads
                        ↓
          Future application adapters
              ↙                  ↘
       Local frontend        MCP / AI agent

The Markdown vault remains the source of truth.

There is deliberately no separate database containing a second canonical copy of the user's identity model. Graph JSON, reports, indexes, and future visualizations are projections that can be rebuilt from the reviewed vault.

Vault Data Model

The vault is organized as a trust lifecycle rather than simply a collection of folders.

vault/
├── 00_raw_artifacts/
│   ├── text/
│   ├── writing/
│   ├── images/
│   └── projects/
│
├── 01_agent_inbox/
│   ├── notes/
│   ├── claims/
│   └── relationships/
│
├── 02_notes/
│   ├── memories/
│   ├── values/
│   ├── beliefs/
│   ├── projects/
│   ├── patterns/
│   ├── decisions/
│   ├── people/
│   ├── questions/
│   └── contradictions/
│
├── 03_canonical_model/
│   ├── claims/
│   └── relationships/
│
└── 04_generated/
    ├── graph/
    └── reports/

Each location communicates something about how much authority the system is allowed to assign to the information stored there.

Raw Artifacts

Raw artifacts are evidence.

They represent source material such as:

Raw artifacts should remain available even if every interpretation derived from them is later rejected.

Agent Inbox

The Agent Inbox contains proposals rather than truth.

Generated notes, claims, and relationships begin here. The inbox creates a hard boundary between machine-assisted organization and human-approved knowledge.

Reviewed Notes

Once accepted, human-readable records move into typed note collections such as:

Canonical Model

More explicitly structured claims and graph relationships live in the canonical model once reviewed.

This gives future systems a machine-oriented representation without sacrificing the underlying Markdown evidence trail.

Generated Outputs

Reports and graph exports are considered derived artifacts.

They can be deleted and regenerated without destroying canonical knowledge.

Stable Identity

Nous assigns records stable IDs rather than relying on filenames.

Examples include:

artifact_2026-06-14_evening-reflection
memory_2026-06-14_first-nous-schema
claim_2026-06-14_systems-building-pattern
edge_2026-06-14_claim-systems-evidenced-by-project

This allows note filenames and organization to evolve without changing graph identity.

Stable IDs are also important for future agents because an agent can request a known record by identity rather than being given arbitrary filesystem access.

Provenance Model

Provenance is one of the most important parts of Nous.

Generated and interpretive records can include metadata such as:

source:
  type:
  path:
  extraction_method:

confidence:
interpretation_level:
evidence:
counterevidence:
review_status:

This lets the system answer questions such as:

The goal is for future AI systems to reason over personal information without erasing the history behind that information.

Text Ingestion

Direct text ingestion provides the simplest path into Nous.

A UTF-8 text or Markdown file can be imported with:

ruby scripts/ingest_text.rb path/to/source.txt

The ingestion path creates:

  1. A raw text artifact.
  2. A conservative draft note in the Agent Inbox.

The input is preserved before downstream interpretation.

Repeated imports do not silently overwrite previous records. Collision handling allocates suffixed filenames so existing information remains intact.

The current direct-capture MVP is deliberately text-only. Voice transcription, audio processing, and always-on capture are not part of the current implementation.

Raw Artifact Imports

Nous expands beyond short text capture through a dedicated artifact ingestion path.

Supported categories include:

Examples:

ruby scripts/ingest_artifact.rb --type writing path/to/journal.md

ruby scripts/ingest_artifact.rb --type image path/to/photo.png

ruby scripts/ingest_artifact.rb --type project path/to/design-spec.json

Each successful import creates:

The external original remains untouched.

Artifact Integrity

Imported artifacts can record:

The copied vault payload becomes the portable evidence record.

This avoids making the knowledge base depend permanently on workstation-specific absolute file paths.

Closed Allowlists

Artifact types use explicit extension allowlists rather than accepting arbitrary files.

This reduces accidental ingestion and narrows the trust boundary around what future readers are expected to understand.

Binary Safety

Images and other supported binary artifacts remain metadata-only by default.

The ingestion layer does not automatically invent:

Additional interpretation can be introduced later through explicit, separately reviewed processing.

Human Review and Curation

Generated personal knowledge should not become canonical simply because software produced it.

Nous therefore includes a review workflow.

Pending records can be listed with:

ruby scripts/review_queue.rb list

A specific item can be inspected with:

ruby scripts/review_queue.rb show <path>

Review decisions include:

When a generic note is approved, the reviewer must explicitly choose its semantic type rather than allowing software to silently promote it.

For example:

ruby scripts/review_queue.rb approve <path> --as memory

Claims and relationships have their own canonical destinations.

Review decisions are preserved in metadata so lifecycle history remains auditable instead of being destroyed.

Relationship Integrity

Graph relationships are treated as reviewable records rather than loose links.

Supported relationship types include:

A relationship cannot become canonical simply because it names two IDs.

Before relationship approval, Nous verifies that both endpoints resolve uniquely to valid active reviewed records.

This prevents relationships from being promoted when they point to:

Graph export performs dangling-endpoint validation again as a second layer of defense.

Knowledge Graph Export

Reviewed personal knowledge can be projected into deterministic graph JSON:

ruby scripts/export_graph.rb

The default output is:

vault/04_generated/graph/nous_graph.json

The graph is intentionally reviewed-only.

It reads from:

It excludes:

The graph does not maintain independent canonical state.

If the exported file disappears, it can be reconstructed from the reviewed Markdown vault.

This design keeps Nous compatible with future graph databases or visualization tools without requiring one to become the source of truth today.

Nous Report

Nous can also generate a human-readable summary of reviewed self-knowledge:

ruby scripts/generate_nous_report.rb

The default report is written to:

vault/04_generated/reports/nous.md

The report can organize trusted records into areas such as:

The report is deterministic and source-backed.

Importantly, it is not an LLM-generated personality analysis.

It can organize and excerpt reviewed information, but it is not allowed to create unsupported psychological conclusions simply to make the report more narratively satisfying.

This keeps the report auditable and makes changes in the generated view explainable through changes in the underlying records.

Agent-Ready Nous Core

A major architectural step was moving product rules underneath the original CLI scripts into a reusable Nous Core.

The current core lives primarily under:

lib/nous.rb
lib/nous/

The command-line scripts are increasingly thin adapters around this domain layer.

This creates a common backend that can eventually serve:

The important constraint is that every interface shares the same rules for:

The frontend and agent integration therefore do not become separate implementations of the product's trust model.

CLI, Application, and MCP Boundary

Nous deliberately separates three concepts.

Nous Core

The core owns deterministic business rules:

Local Application Adapter

A future user interface should call the core directly through a deterministic local application boundary.

Ordinary application actions should not require an LLM tool loop.

MCP Adapter

MCP is planned as the interface through which an external agent can interact with the Nous Core.

It is not intended to become the backend for every product action.

This avoids making normal UI behavior dependent on probabilistic model orchestration.

Nous itself also does not host a model runtime. The knowledge system remains independent from whichever LLM or agent framework ultimately consumes it.

Mutation Safety

Personal knowledge is unusually expensive to corrupt because mistakes can affect the historical record itself.

Nous therefore introduced reusable mutation primitives for filesystem safety.

Current components include:

path_guard.rb
vault_lock.rb
atomic_writer.rb
file_transaction.rb
collision_allocator.rb
review_mutation.rb
relationship_integrity.rb

Vault Containment

Core-controlled paths are checked against the vault boundary.

Traversal and unexpected external-path behavior are rejected instead of being silently followed.

Symlink Protection

Symlink behavior is treated conservatively because an apparently local path can otherwise redirect an operation outside its expected trust boundary.

Vault Locks

Mutations use a vault-scoped lock with operating-system flock semantics.

Reads that require coherent snapshots can use shared locking, while mutations and derived-output replacement use exclusive locking.

This prevents two processes from independently making assumptions about the same vault state while a lifecycle transition is occurring.

Atomic Writes

Output files are staged locally before finalization.

This reduces the chance that interruption leaves partially written Markdown or JSON that later code mistakes for a valid record.

Multi-File Transactions

Operations such as ingestion may create several coordinated files.

Nous tracks invocation-created files so a handled failure can roll back the current operation without deleting pre-existing user records.

Collision Allocation

When target names already exist, new paths are allocated additively rather than overwriting the old records.

For artifact imports, related payload, artifact-note, and inbox-note names can share a coordinated suffix so provenance remains aligned.

Agent-Safe Read Operations

The current agent-facing core exposes bounded read operations, without yet introducing an MCP server.

The primary operations are:

status
list_records
read_record
read_source_text

These form a deliberately narrow interface for future archivist agents.

status

Returns bounded structural information such as:

It does not return arbitrary note bodies or filesystem information.

list_records

Provides deterministic lexical discovery.

Reviewed and canonical knowledge are the default search scopes.

Raw evidence and pending inbox candidates require explicit scope selection.

The current implementation intentionally does not use:

This keeps the core deterministic while the trust contracts are being established.

read_record

Resolves a record through its stable ID and returns a curated bounded representation.

Raw frontmatter is not simply dumped to the caller.

Record bodies are bounded, paths are sanitized, and lifecycle information remains explicit.

read_source_text

Source reading is artifact-ID based rather than arbitrary-path based.

This is an important security boundary.

An agent can request:

artifact_2026-06-14_example

but cannot turn the knowledge tool into a generic filesystem reader by submitting something such as:

../../../../etc/passwd

For copied writing and project text payloads, Nous can validate:

Images and other binary sources return a structured "content unavailable" response rather than bytes, base64, or hallucinated interpretation.

Untrusted Content Boundary

Agent-facing content returned from the vault is explicitly treated as untrusted data.

This matters because personal artifacts may themselves contain instructions, code, copied web content, prompt injection attempts, or text that should not become executable agent policy.

Returning user content as bounded data rather than implicitly trusted instruction is part of the architecture for safely connecting Nous to external AI systems.

Record Discovery

Agent reads use a dedicated RecordIndex abstraction.

The index scans only known record locations and classifies records based on their directory and lifecycle, rather than trusting frontmatter to promote itself into a more authoritative state.

For example, a file placed in the Agent Inbox cannot declare itself canonical merely by changing:

review_status: reviewed

Directory location and lifecycle validation remain part of the trust model.

The index also detects duplicate IDs instead of silently selecting whichever file happens to sort first.

This avoids one of the most dangerous failure modes for a stable-ID knowledge system: ambiguous identity.

Privacy and Trust Boundaries

Privacy is not treated as a later deployment concern.

It is part of the storage and API design.

Nous currently follows several defensive rules:

These constraints deliberately trade convenience for stronger guarantees around long-lived personal data.

Current Milestone Progress

Nous has been developed incrementally so that each stage establishes a contract before the next layer depends on it.

Milestone Capability Status
M1 Vault schema and data model Implemented
M2 Basic text ingestion Implemented
M3 Human review queue Implemented
M4 Reviewed graph export Implemented
M5 Source-backed Nous report Implemented
M6 Writing, image, and project artifact imports Implemented
M7A Agent/core architecture and MCP feasibility boundary Implemented
M7B Reusable read-oriented Nous Core Implemented
M7C Safe reusable mutation core Implemented
M7D Agent-safe bounded read operations Implemented
M7E Candidate-only agent write operations Planned
M7F Local MCP adapter over Nous Core Planned

The project is therefore currently at the point where the deterministic local knowledge core is becoming safe enough to expose to an external archivist agent without giving that agent unrestricted authority over the user's canonical self-model.

Testing and Verification

Nous uses fixture-driven tests and repository-level regression checks rather than relying only on manual verification.

The test suites cover areas including:

Repository checks can be run with:

make test
make lint

A major goal of the test architecture is to make trust-boundary behavior executable.

Instead of documenting only that "agents should not access arbitrary files," the project adds adversarial fixtures proving that traversal and symlink-shaped inputs are rejected.

Likewise, reviewed-only graph/report behavior is regression-tested so future refactoring cannot accidentally allow inbox records into trusted outputs.

Technical Highlights

Local-First by Construction

Nous does not require a hosted backend to maintain the personal knowledge model.

Markdown, YAML, JSON, and copied local artifacts make the data portable and inspectable outside the application itself.

File-First Authority

The vault remains authoritative.

Indexes, reports, and graph exports are rebuildable projections rather than competing databases.

Provenance-Backed Knowledge

Generated records can carry evidence references, source metadata, interpretation level, confidence, counterevidence, and review lifecycle information.

Human-in-the-Loop Canonicalization

AI-generated or machine-generated information enters a candidate state first.

Canonical knowledge requires explicit human review.

Deterministic Derived Outputs

Knowledge graphs and Nous reports can be regenerated from reviewed state.

This makes the system easier to audit and reduces hidden state.

Stable Knowledge Graph Identity

Stable record IDs decouple graph references from filenames and support future migration, visualization, and agent access.

Safe Artifact Preservation

Writing, image, and project imports preserve source bytes and integrity metadata without mutating the original external file.

Explicit Binary Boundaries

Binary sources are not treated as an excuse to perform silent OCR, computer vision, or psychological interpretation.

Reusable Domain Core

CLI behavior has been moved behind reusable library boundaries so future adapters do not need to duplicate lifecycle and security rules.

Transactional Filesystem Mutation

Locking, atomic replacement, scoped rollback, containment checks, and collision allocation reduce corruption risks in a file-based system.

Bounded Agent Access

Future agents interact through stable IDs and curated operations instead of unrestricted paths or raw vault access.

Model-Agnostic Architecture

Nous does not embed a specific LLM provider.

The data system can therefore survive changes in model vendors, agent frameworks, and inference technology.

Challenges

Distinguishing Data From Interpretation

Personal knowledge does not have the same objective ground truth as many software datasets.

A sentence may be:

Representing these differences explicitly is significantly more important than simply storing text.

Preventing AI-Generated Knowledge Drift

A system that repeatedly summarizes its own summaries can gradually construct a fictional representation of the user.

Nous reduces this risk by requiring source references and keeping model-generated candidates separate from reviewed knowledge.

Designing Human Review Without Making Capture Painful

If every captured sentence requires extensive manual classification, the system becomes unusable.

If everything is accepted automatically, the knowledge model becomes untrustworthy.

The review architecture attempts to place human effort specifically at the promotion-to-trusted-knowledge boundary.

File-Based Consistency

A local Markdown system gains portability and transparency but loses database transactions by default.

Building locks, atomic writes, rollback behavior, deterministic collisions, and endpoint validation was necessary to make file-first storage safer under concurrent and multi-file operations.

Arbitrary File Access

An AI agent connected to a local personal knowledge system creates an obvious security risk if "read my memory" quietly becomes "read any file on my computer."

Stable artifact IDs, known directories, path guards, symlink rejection, and curated source-reading rules exist specifically to keep that boundary narrow.

Agent Authority

The hardest architectural question is not how to connect an agent, but how much authority it should receive.

Nous separates agent capabilities from human review authority so future automation can become powerful without implicitly giving a model permission to redefine canonical personal knowledge.

Designing for an Unknown Future Interface

Future uses may include memory chat, graph visualization, personal agents, clone context, or applications that have not yet been designed.

Instead of prematurely building each interface, the project focuses on preserving high-quality, portable underlying data contracts that those interfaces can reuse.

What I Learned

Nous has pushed me to think about AI systems less as isolated model calls and more as long-lived information systems with trust boundaries.

The largest design questions were not about prompt engineering.

They were questions such as:

I also learned that local-first architecture does not automatically mean simple architecture. Once personal files become structured application state, problems such as transactions, locking, identity, schema evolution, path safety, corruption, and audit history become important.

The project has reinforced the value of implementing AI products from the data and trust model outward, rather than starting from the visible chatbot interface and attempting to retrofit reliable memory afterward.

Technologies Used

Future Improvements

The next major step is completing the agent-facing layer without weakening the existing review boundary.

Candidate-Only Agent Writes

Future agent operations should be able to propose:

Those writes should land only in candidate/inbox states.

An agent should not be able to directly promote its own output into the reviewed or canonical model.

Local MCP Adapter

A local stdio MCP server can expose selected Nous Core operations to external agents.

The MCP layer should remain a thin protocol adapter rather than reimplementing product rules.

Archivist Agent

A future archivist agent can consume raw evidence and help:

The archivist should preserve wording and provenance while avoiding unsolicited psychological certainty.

User Interface

A dedicated interface can make Nous easier to use without replacing the file-first vault.

Potential views include:

The frontend should call the same Nous Core used by the CLI rather than introducing a separate set of lifecycle rules.

Memory Chat

A future assistant could answer questions such as:

Answers should cite reviewed notes and underlying source artifacts rather than relying on opaque model memory.

Semantic Retrieval

Current agent search is deliberately lexical.

Once the trust and retrieval contracts are stable, semantic search or embeddings could be introduced as a derived index rather than a new canonical data store.

Temporal Knowledge

Values, beliefs, goals, and relationships change.

A future temporal layer could model:

belief A
    ↓ changed_by
event B
    ↓
belief A'

This would let Nous represent changes in the user's worldview rather than flattening all historical states into one current profile.

Contradiction and Counterevidence Views

Because Nous already models claims and counterevidence, future interfaces could surface unresolved tensions rather than forcing premature consistency.

Richer Artifact Processing

Images, project repositories, documents, and other media could eventually receive explicit processing pipelines.

Any extracted content should remain source-backed and reviewable rather than being merged silently into canonical knowledge.

Personal Knowledge Visualization

Graph and timeline views could visualize:

Consent-Based Interpersonal Graph

A longer-term extension could allow trusted people to maintain their own self-authored data and selectively connect it with another person's Nous graph.

For example:

My Nous ───── shared memory ───── Friend's Nous
    │                                  │
 my perspective                  their perspective
    │                                  │
    └──────── relationship context ────┘

This would require much stronger systems for:

The system should preserve multiple perspectives rather than forcing one participant's interpretation to become universal truth.

Long-Term Vision

The long-term goal of Nous is not simply to remember more information.

It is to create a durable digital representation of personal context that remains inspectable and owned by the person it describes.

As AI systems become more persistent, the quality of the personal data they rely on may become as important as the intelligence of the underlying model.

A sufficiently mature Nous vault could eventually become a personal data substrate for many different systems:

                         Nous
                          │
           ┌──────────────┼──────────────┐
           │              │              │
      Memory Chat     Visualization   AI Agents
           │              │              │
       Reflection     Timeline /       Personal
       & Recall        Graphs          Assistant
           │              │              │
           └──────────────┼──────────────┘
                          │
                  Reviewed Personal
                  Knowledge Model
                          │
                  Source Provenance
                          │
                     Raw Life Data

The central idea is that these interfaces should remain replaceable.

The durable asset is the structured, provenance-backed, human-reviewed knowledge itself.