An - GitLite

KO | EN

gitlite — search

#javascript #python #ai #typescript #golang #android #linux #nodejs #windows #vue #awesome-list #security #mcp #openai

An

(★ 24)

An is a learning system for contextual language help, personal knowledge, and AI-guided review through one MCP.

An Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# An

**Turn a moment of uncertainty into knowledge that can keep growing**

English · [简体中文](README.zh-CN.md)
</div>

An's codebase is still immature, but its direction is clear.

An begins with a natural action: select text in any application, press a shortcut, receive a contextual explanation or Chinese–English translation, and preserve that learning moment reliably.

But An is not just a lookup tool or a review plugin. Its long-term direction is to become a bridge between people, professional knowledge, and AI.

You can place Markdown notes, articles, papers, or books in your own Knowledge Base while preserving every original byte.

Codex and ChatGPT can then use the same MCP to search, read, discuss, summarize, practise, and review within the exact scope you choose.

In An, AI is a guide to knowledge. It should first tell you what the Knowledge Base contains, which Folder a file will enter, and what an operation will change. Only then should it add, move, delete, search, or review.

## What problem An solves

Today's AI is very good at answering questions, but it struggles to understand what a person has genuinely learned over time.

A lookup remains in a popup. A paper is trapped in one conversation. Learning records are scattered across devices, and review is often compressed into rigid flashcards.

An connects these parts into a traceable learning path:

1. **Ask for help at the point of uncertainty.** An processes the current Selection only after an explicit user action. Selecting text alone never sends or stores anything.
2. **Preserve facts before generating views.** A successful Record enters a local transactional database first, then projects into one readable Markdown log per day.
3. **Turn source material into manageable knowledge.** Imported Markdown remains byte-for-byte unchanged. Segments, indexes, and AI-generated headings are rebuildable derived data.
4. **Let the user choose the exact scope.** Search, summarization, discussion, and review can be limited to a Folder, Source, version, section, or explicit learning objective.
5. **Support the way each person learns best.** Explanation, Socratic questioning, Feynman teach-back, Temporary Practice, and spaced review can coexist. No paragraph has to become a flashcard.

## One product, three connected learning layers

### 1. Desktop Language Request

Select text in another Windows or macOS application, then explicitly invoke An to:

- explain what the Selection means in its source language and current context;
- translate between Chinese and English while preserving meaning;
- record a successful request as a traceable Record; and
- keep lookup, explanation, and local recording available when the cloud is unavailable.

The desktop side is responsible only for the global shortcut, Selection and bounded context capture, system permissions, and the native Result Window.

The shared Rust engine handles request validation, Codex App Server communication, local transactions, the sync Outbox, and Markdown projection.

### 2. Personal Knowledge Base

An Account owns one complete Knowledge Base. Separate databases do not belong to each computer, city, or ChatGPT conversation.

```text
An Account
└── Knowledge Base
    ├── Folder
    │   ├── Source
    │   │   ├── immutable Version 1
    │   │   └── immutable Version 2
    │   └── Source
    └── Folder
```

- A **Folder** is a user-named scope in a tree. It can follow a course, project, person, or any organization the user prefers.
- A **Source** is an article, paper, book, or note.
- A **Source Version** is the immutable original from one import. Importing it again creates a new version instead of overwriting history.
- An **Indexing Plan** describes how the material can be retrieved without rewriting the original.

Codex is the mature Version 0.1.0 entry point for knowledge compilation, upload, and writes.

After connecting to An, it should first report the Folders, Sources, versions, and device provenance currently visible to the cloud. It then asks the user to confirm the destination and structure.

The user can add, move, rename, archive, restore, delete, search, and choose scope in natural language without a separate An management dashboard.

ChatGPT and Codex use the same MCP, account boundary, and knowledge rules. Capabilities are not hard-coded by product name on the server, but public claims follow real-client tests.

The current ChatGPT target is reading, retrieval, discussion, summarization, and rule-based Temporary Practice. An does not claim that ChatGPT can yet reliably upload, write back, or update formal review progress.

### 3. AI-guided Review

An Review is one capability of the Knowledge Base, not the name of the whole product.

Importing a document, segmenting a paragraph, or looking up a word repeatedly does not create a review schedule.

Formal scheduling begins only when the user confirms an independently assessable **Review Target** with a learning objective, answer criteria, and grading rules.

This lets An support all of the following:

- “Explain the principle of proportionality clearly first.”
- “Now let me explain it back in my own words.”
- “Keep questioning the parts I got wrong.”
- “Practise only these three knowledge points I have confirmed from this course.”
- “Record this genuine retrieval as Again, Hard, Good, or Easy.”

FSRS-6 schedules only confirmed Review Targets. A model may submit only the final grade, never Stability, Difficulty, Retrievability, an interval, or the next review time.

Before a formal write, the AI must state its proposed grade and allow the user to correct it. If the current client cannot complete the write, teaching may continue, but it must say that progress and scheduling were not updated.

## How Markdown enters An

Version 0.1.0 uses three explicit compilation modes. Users can choose according to the quality of their material:

1. **Respect Existing Structure.** Markdown with clear headings or explicit blocks keeps the author's structure and is not forced through another segmentation pass.
2. **Deterministic Segmentation.** Headings, paragraphs, and length boundaries divide the text mechanically. The result is inexpensive and stable; it improves retrieval without pretending to understand every semantic relationship.
3. **AI-assisted Structure.** Codex analyses the document's flow and generates derived headings or an organization plan. This suits OCR output and weakly structured long-form text. Generated content is labelled, and the original remains untouched.

In every mode:

- the original Markdown is stored as immutable bytes;
- every slice points back to an exact byte range in the source;
- slices must cover the source completely, with no summarization, translation, omission, or hidden rewrite;
- derived indexes can be deleted and rebuilt; and
- a mechanical slice is not a Review Target, and AI cannot create review questions solely from paragraph boundaries.

The local compiler first produces a verifiable Source, Version, and Indexing Plan. A dedicated uploader transfers the real file bytes directly, so they do not need to be placed in model context.

Before publication, the cloud validates account authorization, content hashes, the manifest, and complete slice coverage. An incomplete import never appears as searchable knowledge.

## Current status

The domain code, cloud service, Plugin, Skills, database migrations, and automated tests for An's MCP, knowledge model, and review system are already in this repository.

The current boundary is that **production deployment and real-account acceptance are not yet complete**—not that development of these capabilities has not begun.

| Capability | Repository status | First public Windows alpha boundary |
| --- | --- | --- |
| Windows Selection explanation and Chinese–English translation | Implemented and accepted in the current candidate | Included |
| Native Result Window and Language Preferences | Implemented; the accepted Windows UI is frozen | Included |
| Local transactions, Outbox, and Daily Log | Implemented with automated tests | Included |
| macOS native shell | Source and automated checks are in the repository | Installer follows after macOS interaction tests pass |
| Byte-preserving Knowledge Compiler | Implemented with tests | Source is public; cloud import is not enabled in the `local-only` installer |
| Folder, Source Version, and recoverable management | Implemented with tests | Requires the invitation cloud and real-account acceptance |
| Authenticated transfer and knowledge publication | Main path implemented with tests | Opens after Auth0, PostgreSQL, object-storage, and recovery gates |
| Shared MCP and four canonical Skills | Implemented and package-contract verified | Invitation-only; not the same as submission to the public Plugin directory |
| FSRS-6 Review Domain and cloud scheduling | Implemented with one shared Rust authority | Formal grades are accepted only after Cloud Authority Cutover |
| ChatGPT retrieval and Temporary Practice | Uses the same MCP contract | Only read capabilities verified in real clients are claimed |
| ChatGPT writes and ChatGPT Voice | The contract does not block future capabilities | Not currently claimed |

## Windows `v0.1.0-alpha.1`

The first public native package is planned as:

```text
An-0.1.0-alpha.1-Windows-x64-local-only.zip
```

The `local-only` label is an honest delivery boundary. This package provides the accepted desktop Language Request workflow, local recording, and Markdown projection.

It does not present cloud Knowledge, sync, or formal Review as available before their production gates pass. The full Knowledge, MCP, and cloud source is still published with the repository.

Requirements:

- 64-bit Windows 10 or Windows 11;
- Codex installed locally; and
- a signed-in Codex account.

After launch, An appears only in the notification area and opens no normal main window. ChatGPT serves as its primary UI.

Select text in another application, then press the default `Ctrl+Alt+A` shortcut. Each of the four Language Preferences can be enabled or disabled independently.

Selection support still depends on the target application's Accessibility and clipboard behavior.

Native applications, Chromium pages, Google Docs, WPS, and PDF readers are part of the test matrix, but behavior may still vary by version. Include the application name and a non-sensitive reproduction when reporting a capture failure.

## Local records

Before An reports that a request was saved, it commits the successful request and its pending sync state in one local transaction. It then creates one Markdown projection per day:

```text
Documents/An Review/Daily Logs/YYYY/MM/YYYY-MM-DD.md
```

This is a readable, rebuildable system projection. It is not the scheduling database or one file per request. Direct edits to managed logs may be replaced during reconstruction.

## Privacy and security boundaries

- Selected text is sent to the local Codex App Server only after the user explicitly triggers a Language Request.
- Surrounding context is used only for disambiguation and is not written to the Daily Log or synchronized by default.
- An never reads, copies, logs, or stores Codex credentials. Model access uses the user's existing local Codex session.
- Language Requests, Device Sync, MCP, and Knowledge Transfer use separate authentication boundaries and credentials.
- An Account comes from a verified An OAuth identity, not from a device, city, operating system, ChatGPT account, or Codex account.
- Password, protected-content, credential, remote-session, and ambiguous-focus surfaces fail closed.
- Imported Markdown remains immutable; indexes are rebuildable derived data.

The hosted service is not end-to-end encrypted because it must search content and calculate review schedules.

Before invitations open, public privacy material must clearly describe retention, export, deletion, backups, and account revocation.

## Architecture

```text
Windows / macOS native shell
            │ versioned JSONL over local stdio
            ▼
      shared Rust engine ── local SQLite + Markdown projections
            │ background Device Sync
            ▼
      An cloud application service
       ├── PostgreSQL event ledger and projections
       ├── immutable source/object storage
       └── one account-scoped MCP
                    │
              Codex / ChatGPT
```

Key constraints:

- Native shells own platform behavior; the shared engine owns business logic and local persistence. They do not communicate over local HTTP.
- `language-core` has no platform API, filesystem, network, or process-management dependency.
- `review-domain` is the single FSRS-6 authority and has no platform, network, database, OAuth, or MCP dependency.
- Device Sync and MCP are separate adapters. They share an account-scoped application service, but not client credentials.
- Cloud failure delays synchronization and formal Review only. It never blocks desktop explanation, translation, or local recording.

## Build from source

The repository pins Rust through `rust-toolchain.toml`. Windows builds require Visual C++ Build Tools.

Run from the repository root:

```text
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```

Build in a native Windows developer shell:

```powershell
$env:RUSTFLAGS = '-C target-feature=+crt-static'
cargo build --release --target x86_64-pc-windows-msvc --package an-windows-shell
cargo build --release --target x86_64-pc-windows-msvc --package language-engine
```

The cloud service and Plugin have separate gates:

```text
cargo clippy --manifest-path services/cloud-review-service/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path services/cloud-review-service/Cargo.toml --all-targets
node plugins/an-review/tests/verify-package.mjs
```

macOS development requires Xcode and both Apple Rust targets. The source builds and tests in CI.

Accessibility, focus, animation, and cross-application interaction must be exercised on the M1 Mac before they are described as verified.

## Repository map

```text
apps/windows                  Windows native shell
apps/macos                    macOS native shell
crates/language-core          platform-independent Language Request rules
crates/engine                 Codex, local recording, sync, and JSONL engine
crates/knowledge-compiler     byte-preserving Markdown Knowledge Compiler
crates/review-domain          shared FSRS-6 review domain
services/cloud-review-service account, sync, Knowledge, MCP, and review cloud
tools/an-knowledge             local Knowledge inspection and transfer CLI
plugins/an-review              shared An Plugin and Skills source
docs                           ADRs, specifications, research, and test evidence
```

## What comes next

1. Complete the production composition and real-account tests for Auth0, PostgreSQL, object storage, and multi-process recovery.
2. Open a controlled invitation flow and verify account isolation, export, deletion, revocation, and cross-device consistency.
3. Verify retrieval, management, upload, Review, and Voice capability by capability in real Codex and ChatGPT clients.
4. Complete the Mac interaction matrix and publish the macOS installer.
5. Provide a simple, diagnosable self-hosting golden path that gives precise repair guidance when installation fails.

An permits self-hosting, but Version 0.1.0 will not pretend that the current deployment path is already effortless.

A one-command or guided installer is still being designed. Until it exists, the README will identify which steps are for project maintainers instead of asking ordinary users to decipher container logs.

## Contributing

Issues, reproducible cases, and small, focused Pull Requests are welcome. Never attach real Selection content, access tokens, local databases, OAuth configuration, or cloud exports to an Issue.

An is still a fast-moving `0.1.0` project. Public source reflects genuine development progress.

“Implemented in the repository,” “automatically verified,” “deployed to the invitation environment,” and “released to everyone” are four different gates. The documentation will continue to distinguish them.

## License

An is licensed under the [Apache License 2.0](LICENSE). See [NOTICE](NOTICE) and the included third-party notices.

An

An Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

An

An Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README